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/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.
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 palette slot for its border and title color:
| Type | Palette Slot | Typical Color |
|---|---|---|
| Note | p4 | Blue |
| Tip | p2 | Green |
| Info | p6 | Cyan |
| Warning | p3 | Yellow |
| Danger | p1 | Red |
Tip
For a complete list of all available components including admonitions, code blocks, and more, see the Components reference.
i18n (Internationalization)
zudo-doc supports English and Japanese out of the box. Japanese docs mirror the English directory structure in src/.
Tip
See the i18n guide for detailed instructions on managing translations and language routing.
MDX Features
You can use Preact components in your documentation. Interactive components hydrate on the client via zfb's island runtime — the rest ships as pure HTML with zero JavaScript.
import MyComponent from "@/components/my-component";
<MyComponent />Info
A plain component import renders server-side only and ships zero JavaScript. Interactive islands are registered via the project's island runtime — a bare component import does not hydrate on the client; only components wired up as islands do.
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