Writing Docs

How to create and organize documentation pages in zudo-doc.

Creating a Document

Create an .mdx file in src/content/docs/. Use frontmatter for metadata:

---
title: My Page
description: A brief summary of this page.
sidebar_position: 1
---

Your content here.

Frontmatter 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)

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:

Custom Titles

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:

i18n (Internationalization)

The default scaffold has one primary locale and no additional-locale directory or locale route. Set --additional-langs ja,de (or use the equivalent preset/API field) to create src/content/docs-ja/ and src/content/docs-de/, with pages/[locale]/docs/[[...slug]].tsx serving /ja/docs/... and /de/docs/.... The primary content remains in src/content/docs/ at /docs/...; add or remove additional locales later through the locales field in zudoDoc({ ... }).

Keep each configured tree structurally aligned: use the same relative filenames, frontmatter, code blocks, and JSX examples, translating the prose in each locale. The ja starter is Japanese; arbitrary non-JA locale trees begin with English placeholder prose and must be translated before publishing. The language switcher follows configured labels and order, and UI strings fall back from requested locale to default locale, package English, then the raw key.

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/components/my-component.tsx imports as:

import MyComponent from "@/components/my-component";

<MyComponent />

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