## Creating a Document
Create an `.mdx` file in `src/content/docs/`. Use frontmatter for metadata:
```mdx
---
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 |
[Dynamic content unavailable in text export]
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.
[Dynamic content unavailable in text export]
See the [Frontmatter guide](https://zudo-doc.takazudomodular.com/docs/guides/frontmatter) 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**:
```mdx
[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:
```mdx
[Frontmatter fields](../guides/frontmatter.mdx#required-fields)
```
[Dynamic content unavailable in text export]
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:
```mdx
[External site](https://example.com)
[API reference](/api/v1)
```
## Admonitions
zudo-doc supports Docusaurus-style admonitions. They are registered globally — no imports needed:
[Dynamic content unavailable in text export]
This is a **note** — use it for general information that readers should be aware of.
[Dynamic content unavailable in text export]
This is a **tip** — use it for helpful suggestions and best practices.
[Dynamic content unavailable in text export]
This is an **info** block — use it for additional context or background information.
[Dynamic content unavailable in text export]
This is a **warning** — use it to flag potential issues or things to watch out for.
[Dynamic content unavailable in text export]
This is a **danger** alert — use it for critical warnings about data loss or breaking changes.
[Dynamic content unavailable in text export]
This is a **caution** alert — high-severity and danger-adjacent; it is also what GitHub-style `[!CAUTION]` alerts render as.
### Custom Titles
[Dynamic content unavailable in text export]
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):
```mdx
:::note[Optional Title]
Content here.
:::
```
**JSX component syntax**:
```mdx
Default note with auto-generated title.
Warning with a custom title.
```
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 |
[Dynamic content unavailable in text export]
For a complete list of all available components including admonitions, code blocks, and more, see the [Components](https://zudo-doc.takazudomodular.com/docs/components) reference.
## 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.
[Dynamic content unavailable in text export]
See the [i18n guide](https://zudo-doc.takazudomodular.com/docs/guides/i18n) for detailed instructions on managing translations and language routing.
## MDX Features
You can use zudo-react 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:
```mdx
import MyComponent from "@/components/my-component";
```
[Dynamic content unavailable in text export]
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](https://zudo-doc.takazudomodular.com/docs/guides/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_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