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). Starting 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: 2Each 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:
[Astro docs](https://docs.astro.build)
[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 as Astro islands — the rest ships as pure HTML with zero JavaScript.
import MyComponent from "@/components/my-component";
<MyComponent client:load />ℹ️ Info
Use client:load for components that need interactivity. Omit it for components that only render static HTML.
Navigation
zudo-doc automatically generates:
- Sidebar — collapsible categories with items sorted by
sidebar_position - Table 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