Writing Docs
How to create and organize documentation pages in zudo-doc.
Creating a Document
Create an .mdx file in src/. Use frontmatter for metadata:
---
title: My Page
description: A brief summary of this page.
sidebar_position: 1
---
Your content here.Frontmatter Fields
| Field | Type | Required | Description |
|---|---|---|---|
title | string | Yes | Page title (shown in sidebar and header) |
description | string | No | Subtitle shown below the title |
sidebar_position | number | No | Sort order within category (lower = first) |
sidebar_label | string | No | Override sidebar display label |
Warning
Do not use # h1 headings in your document content. The frontmatter title is automatically rendered as the page title (h1). Start your content with ## h2 headings instead.
Note
See the Frontmatter guide for the complete reference of all available fields.
Directory Structure
Organize docs into categories using directories:
src/content/docs/
getting-started/
introduction.mdx # sidebar_position: 1
installation.mdx # sidebar_position: 2
writing-docs.mdx # sidebar_position: 3
guides/
configuration.mdx # sidebar_position: 1
sidebar.mdx # sidebar_position: 2 Each directory becomes a collapsible sidebar category automatically. The category name is derived from the directory name (kebab-case converted to Title Case).
Linking Between Documents
You can link to other documents using relative file paths:
[Installation guide](./installation.mdx)
[Frontmatter reference](../guides/frontmatter.mdx)
[Back to index](./index.mdx)These relative paths are automatically resolved to the correct URLs at build time. The .md/.mdx extension is required for the link resolver to work — it distinguishes file links from URL links.
You can also include anchors and query strings:
[Frontmatter fields](../guides/frontmatter.mdx#required-fields)Tip
Relative links are validated during build. If a linked file doesn't exist, you'll see a warning in the build output. This helps catch broken links early.
For external links or links to non-document pages, use regular URLs:
[External site](https://example.com)
[API reference](/api/v1)Admonitions
zudo-doc supports Docusaurus-style admonitions. They are registered globally — no imports needed:
Note
This is a note — use it for general information that readers should be aware of.
Tip
This is a tip — use it for helpful suggestions and best practices.
Info
This is an info block — use it for additional context or background information.
Warning
This is a warning — use it to flag potential issues or things to watch out for.
Danger
This is a danger alert — use it for critical warnings about data loss or breaking changes.
Caution
This is a caution alert — high-severity and danger-adjacent; it is also what GitHub-style [!CAUTION] alerts render as.
Custom Titles
Custom Title
You can provide a custom title to any admonition using the title prop.
Admonition Syntax
Two syntaxes are supported. No imports needed for either.
Directive syntax (recommended for content authors):
:::note[Optional Title]
Content here.
:::JSX component syntax:
<Note>
Default note with auto-generated title.
</Note>
<Warning title="Be Careful">
Warning with a custom title.
</Warning>Each admonition type maps to a semantic color token for its border and title color:
| Type | Color Token | Typical Color |
|---|---|---|
| Note | accent | Orange |
| Tip | success | Green |
| Info | info | Blue |
| Warning | warning | Yellow |
| Danger | danger | Red |
| Caution | danger | Red |
Tip
For a complete list of all available components including admonitions, code blocks, and more, see the Components reference.
i18n (Internationalization)
The default scaffold has one locale and no src/ directory or locale route. Select the i18n feature during scaffolding to add a secondary language, its mirrored content directory, and pages/[locale]/docs/[[...slug]].tsx. You can also add locales later through the locales field in zudoDoc({ ... }).
Tip
See the i18n guide for detailed instructions on managing translations and language routing.
MDX Features
You can use Preact components in your documentation. A plain MDX component import renders on the server and ships as HTML with zero JavaScript.
A fresh scaffold has no src/components/ directory — you create one when you want custom components. The @/* path alias maps to src/*, so a file at src/ imports as:
import MyComponent from "@/components/my-component";
<MyComponent />Info
A plain component import renders server-side only and ships zero JavaScript. To register a component for use across documents or to add an interactive island, follow Custom Components: it uses mdxExtras for global registration and the experimental Island() recipe for client hydration.
Navigation
zudo-doc automatically generates:
Sidebar — collapsible categories with items sorted by
sidebar_positionTable of Contents — right sidebar with h2–h4 headings (visible on wide screens)
Prev/Next links — bottom navigation between docs
Breadcrumbs — category path shown above the title