Content

Heyo Docs treats the configured content directory as the source of every hand-written documentation page. MDX files are compiled during development and build, then become routes, metadata, search records, and optional Markdown mirrors.

The example configuration uses content, so a file at content/guides/install.mdx is available at /guides/install.

Choose the content directory

The content option is relative to the application root:

export default heyoDocs({
  content: "content",
});

content and ./content are equivalent. Keep all referenced pages inside that directory: navigation references cannot use .. to escape it. Local OpenAPI documents use this same directory unless their schema source starts with / to explicitly select public.

Turn files into routes

Routes follow the path below content and omit the MDX extension.

Create the page first, then add its extension-free reference to a configured navigation section. A scanned page can have a route without appearing in the sidebar; listing it in groups makes it discoverable and includes it in the configured reading order.

Add useful frontmatter

Frontmatter is optional, but every reader-facing page should normally set a title and description:

---title: Install the SDKdescription: Add the Acme SDK to a TypeScript service and verify the first request.---# Install the SDKInstall the package, configure a client, and make a test request.

The title appears in navigation, page metadata, breadcrumbs, search results, and previous/next links. The description is the preferred search and social excerpt. If no title is supplied, Heyo Docs uses the first level-one heading and then a title inferred from the URL; page SEO falls back to the site description when a page description is absent.

Use one # heading for the article title, ## for major sections, and ### for details that should appear nested in the right-side table of contents.

Use Markdown and MDX

Regular Markdown works for prose, links, lists, tables, and fenced code:

Install the package:

```bash
bun add @acme/sdk
```

Built-in documentation components can be used directly in any MDX page without an import. For example, use <Callout> for a notable instruction, <Tabs> for alternatives, and <Steps> for an ordered workflow. See the Components section for the complete set and its supported props.

Keep interactive React components focused on documentation. MDX is compiled as part of the application, so a component error is a build error rather than content that can be repaired after deployment.

Reference local assets

Relative assets beside an MDX page are bundled with the application:

![Project architecture](./assets/architecture.svg)<Image  src="./assets/dashboard.png"  alt="The Acme dashboard after sign-in."  caption="The project overview."/><File  src="./downloads/quick-reference.pdf"  name="Quick reference"  description="Printable PDF"/>

Use a root-relative URL such as /logo.svg for files in public. Use a relative URL for assets that belong to a specific article so the bundler can copy and fingerprint them with that page. Standard Markdown links to local files are bundled as well.

Images, video, and downloads have dedicated Image, Video, and File MDX components when a caption or a styled download card is useful.

Keep content reviewable

Prefer small, topic-focused files over one large manual. Give each article a specific title, description, and a predictable folder location. Move a page in the navigation configuration only when that improves reader flow; the physical directory can remain organized around the product area.

Run a production build before publishing. It compiles every MDX file, resolves local media, creates the search index, and catches invalid page references before the files are deployed.