Every MDX file in zudo-doc starts with a YAML frontmatter block delimited by `---`. This page documents all available fields. ## Complete Example ```mdx --- title: My Documentation Page description: A comprehensive guide to something important. sidebar_position: 3 sidebar_label: My Page tags: [type:tutorial, setup] --- Your content here. ``` ## Minimal Example Only `title` is required: ```mdx --- title: Quick Start --- ``` ## Field Overview | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `title` | string | Yes | -- | Page title shown in heading, sidebar, and browser tab | | `description` | string | No | -- | Subtitle shown below the title | | `sidebar_position` | number | No | `999` | Sort order within the sidebar category | | `sidebar_label` | string | No | Value of `title` | Override label shown in sidebar | | `sidebar_initial_expansion` | `"collapsed"` or `"expanded"` | No | Inherited, then legacy behavior | Initial sidebar disclosure; category indexes pass the setting to descendants | | `category` | string | No | Directory name | Reserved for future use | | `category_no_page` | boolean | No | `false` | Makes the category a non-linked header (no route, sitemap entry, or search entry) | | `category_sort_order` | `"asc" \| "desc"` | No | `"asc"` | Sort order for pages within the category | | `category_shape` | `"note-tray"` | No | Regular tree | Makes a top-level, flat category a note tray | | `note_tray_dated` | boolean | No | `false` | Requires every note-tray item to have `date` | | `note_tray_sidebar` | `"index" \| "year" \| "month"` | No | `"index"` | Selects the note-tray sidebar presentation | | `date` | `"YYYY-MM-DD"` | No | — | Document date; required for items in a dated note tray | | `updated` | `"YYYY-MM-DD"` | No | — | Optional update date on any document | | `search_exclude` | boolean | No | `false` | Exclude the page from search indexing | | `tags` | string[] | No | -- | Tags for cross-cutting navigation | | `draft` | boolean | No | `false` | Exclude from production build (visible in dev) | | `unlisted` | boolean | No | `false` | Built but hidden from sidebar, search, and search engines | | `hide_sidebar` | boolean | No | `false` | Hide the left sidebar, center content in a narrower container | | `hide_toc` | boolean | No | `false` | Hide the right-side table of contents | | `wide` | boolean | No | `false` | Widen the content band to fill most of the viewport (full-width layout) | | `doc_history` | boolean | No | Auto | Override doc-history button visibility (auto: hidden on `*/index` pages, shown on detail pages) | | `standalone` | boolean | No | `false` | Hidden from sidebar nav but still indexed (unlike `unlisted`) | | `slug` | string | No | Derived from file path | Custom URL slug override | | `generated` | boolean | No | `false` | Marks build-time auto-generated content; exempts the page from the configured-locale translation requirement | | `pagination_next` | string \| null | No | Auto | Override next page link, set to `null` to hide | | `pagination_prev` | string \| null | No | Auto | Override previous page link, set to `null` to hide | ## Fields ### `title` - **Type:** `string` - **Required:** Yes The page title. It is displayed as the `h1` heading on the page, in the sidebar navigation, in the browser tab, and in search results. ```mdx --- title: Getting Started with zudo-doc --- ``` ### `description` - **Type:** `string` - **Required:** No A short description or subtitle for the page. Shown below the title on the rendered page. Also useful for SEO meta tags. ```mdx --- title: Installation description: How to install and set up zudo-doc for your project. --- ``` ### `sidebar_position` - **Type:** `number` - **Required:** No - **Default:** `999` (appears at the end) Controls the sort order of the page within its sidebar category. Lower numbers appear first. ```mdx --- title: Introduction sidebar_position: 1 --- ``` [Dynamic content unavailable in text export] For category index pages (`index.mdx`), the `sidebar_position` also controls where the entire category appears relative to other categories in the sidebar. ### `sidebar_label` - **Type:** `string` - **Required:** No - **Default:** Value of `title` Overrides the label displayed in the sidebar navigation. Use this when you want a shorter or different label than the full page title. ```mdx --- title: Configuring Color Schemes and Themes sidebar_label: Color Schemes --- ``` ### `category` - **Type:** `string` - **Required:** No - **Default:** Derived from the directory structure (first directory segment) Reserved for future use. This field is defined in the content schema but is not currently used by the sidebar or routing logic. Categories are always derived from the directory structure. [Dynamic content unavailable in text export] Organize pages into categories by placing them in directories under `src/content/docs/`. The directory name becomes the category name. ### `category_no_page` - **Type:** `boolean` - **Required:** No - **Default:** `false` When set to `true` on a category `index.mdx`, the category appears as a non-linked header in the sidebar. No route, sitemap entry, or search entry is generated for the index page itself — it exists solely to label and group the pages beneath it. ```mdx --- title: Internals category_no_page: true sidebar_position: 10 --- ``` ### `category_sort_order` - **Type:** `string` - **Required:** No - **Default:** — (ascending by `sidebar_position`) When set on a category `index.mdx`, overrides the default ascending sort order for pages within that category. Set to `"desc"` for newest-first ordering (useful for changelog or release-notes categories where the most recent entry should appear at the top). ```mdx --- title: Changelog category_sort_order: "desc" sidebar_position: 20 --- ``` For a note tray, this order is used consistently by the sidebar, `NoteTrayIndex`, previous/next pager, and home page. See [Note Trays](https://zudo-doc.takazudomodular.com/docs/guides/note-tray). ### `category_shape` - **Type:** `"note-tray"` - **Required:** No - **Default:** Regular tree category Set `category_shape: "note-tray"` on a top-level category's `index.mdx` to make its direct child files a flat, ordered sequence. A note tray requires a visible routed index and does not permit child directories. ```mdx --- title: Notes sidebar_position: 3 category_shape: "note-tray" --- ``` ### `note_tray_dated` - **Type:** `boolean` - **Required:** No - **Default:** `false` When `true` on a note-tray index, every item in the tray must have `date`, including `unlisted` items. The build reports every offending slug. ### `note_tray_sidebar` - **Type:** `"index" | "year" | "month"` - **Required:** No - **Default:** `"index"` Selects the sidebar presentation for a note tray. `index` shows stable ranks; `year` and `month` group items chronologically and require `note_tray_dated: true`. ### `date` - **Type:** `"YYYY-MM-DD"` - **Required:** Only for every item in a dated note tray Sets the document date. Quoting is optional because zfb keeps the scalar value as a string either way. The schema validates the `YYYY-MM-DD` format, and the build rejects impossible calendar dates. Quote the value for interoperability only when another YAML 1.1 tool, such as js-yaml, consumes this field and would coerce a bare date into a `Date` object. `date` and `updated` are always **authored** as `YYYY-MM-DD`, whatever the [`dateFormat`](https://zudo-doc.takazudomodular.com/docs/guides/configuration#content-and-i18n-dateformat) setting is: that setting changes only how dates are displayed, and the schema validates the raw frontmatter value against a strict `YYYY-MM-DD` pattern regardless. ```mdx --- title: Project Note sidebar_position: 1 date: "2026-08-20" --- ``` ### `updated` - **Type:** `"YYYY-MM-DD"` - **Required:** No Sets an optional update date on any document. It appears beside `date` in the document header and on dated note-tray index and home-page surfaces. It can appear by itself when `date` is absent. The sidebar and pager never show `updated`. ### `search_exclude` - **Type:** `boolean` - **Required:** No - **Default:** `false` When set to `true`, excludes the page from the search index. Useful for internal pages, changelogs, or imported content that should not appear in search results. ```mdx --- title: Internal Changelog search_exclude: true --- ``` ### `tags` - **Type:** `string[]` - **Required:** No Assigns tags to the page for cross-cutting navigation. Tags are displayed as clickable badges on the page, and tag index pages are auto-generated at `/docs/tags/` and `/docs/tags/[tag]`. See the [Tags guide](https://zudo-doc.takazudomodular.com/docs/guides/tags) for a full walkthrough. Tagged pages surface in three places: 1. **Bottom of each doc** — a row of tag badges appears on every tagged page, just above the previous/next pager. 2. **Homepage** — an "All tags" section lists every tag used in the docs, linking to individual tag index pages. 3. **Tag index** — a shared index at [/docs/tags/](/docs/tags/) groups all pages by tag. ```mdx --- title: Deploying to Netlify tags: [deployment, netlify, hosting] --- ``` [Dynamic content unavailable in text export] Tags are useful for grouping related pages across different sidebar categories. ### `draft` - **Type:** `boolean` - **Required:** No - **Default:** `false` When set to `true`, the page is excluded from the production build entirely. Draft pages are still visible during development (`pnpm dev`) for preview purposes. ```mdx --- title: Upcoming Feature draft: true --- ``` ### `unlisted` - **Type:** `boolean` - **Required:** No - **Default:** `false` When set to `true`, the page is built and accessible via its URL, but is hidden from the sidebar navigation, search index, and search engines (via `noindex` meta tag). ```mdx --- title: Internal Notes unlisted: true --- ``` ### `hide_sidebar` - **Type:** `boolean` - **Required:** No - **Default:** `false` When set to `true`, the left sidebar is hidden on desktop and the content is centered in a narrower container. The mobile hamburger menu still provides access to navigation. Useful for landing pages, standalone articles, or any page where a full-width reading experience is preferred. ```mdx --- title: About This Project hide_sidebar: true --- ``` [Dynamic content unavailable in text export] See the [live demo](https://zudo-doc.takazudomodular.com/docs/guides/layout-demos/hide-sidebar) to experience this layout option in action. ### `hide_toc` - **Type:** `boolean` - **Required:** No - **Default:** `false` When set to `true`, the right-side table of contents (section navigation) and the mobile TOC are both hidden. The main content area expands to fill the available width. ```mdx --- title: Changelog hide_toc: true --- ``` [Dynamic content unavailable in text export] See the [live demo](https://zudo-doc.takazudomodular.com/docs/guides/layout-demos/hide-toc) to experience this layout option in action. [Dynamic content unavailable in text export] Combine `hide_sidebar` and `hide_toc` to create a clean, centered reading layout with no navigation panels: ```mdx --- title: About hide_sidebar: true hide_toc: true --- ``` See the [live demo](https://zudo-doc.takazudomodular.com/docs/guides/layout-demos/hide-both) to see both options combined. ### `wide` - **Type:** `boolean` - **Required:** No - **Default:** `false` When set to `true`, the content band widens to fill most of the viewport instead of the standard capped reading column. This suits grid-heavy or dashboard-style pages — for example a home page whose category grid reads better spread across the full width. It pairs naturally with `hide_sidebar`: on a `hide_sidebar` page the content is normally centered at a fixed reading width, and adding `wide: true` lets that content span the viewport. ```mdx --- title: Overview hide_sidebar: true wide: true --- ``` [Dynamic content unavailable in text export] See the [live demo](https://zudo-doc.takazudomodular.com/docs/guides/layout-demos/wide) to experience this layout option in action. ### `standalone` - **Type:** `boolean` - **Required:** No - **Default:** `false` When set to `true`, the page is hidden from sidebar navigation and site index but remains accessible via its URL and is still indexed by search engines. Unlike `unlisted`, standalone pages do not get a `noindex` meta tag. In addition, the page renders without the sidebar and table of contents chrome — equivalent to combining `hide_sidebar: true` and `hide_toc: true`. ```mdx --- title: Terms of Service standalone: true --- ``` [Dynamic content unavailable in text export] Use `standalone` for pages that should be publicly accessible but don't belong in the documentation navigation (e.g., legal pages, special landing pages). Use `unlisted` when you also want to prevent search engine indexing. ### `slug` - **Type:** `string` - **Required:** No - **Default:** Derived from the file path Overrides the URL slug for the page. Use this when you want a different URL than what the file path would produce. ```mdx --- title: Getting Started with zudo-doc slug: quickstart --- ``` This page would be accessible at `/docs/quickstart` instead of the default path derived from its file location. ### `generated` - **Type:** `boolean` - **Required:** No - **Default:** `false` Marks a page as build-time auto-generated content (for example, the `claude-*` reference pages produced from `.claude/` source files). Setting `generated: true` exempts the page from the configured-locale translation rule — auto-generated pages do not require matching copies under `docs-/`. The field is also a framework-managed key, so it is hidden from the frontmatter preview by default. ```mdx --- title: Auto-generated Reference generated: true --- ``` [Dynamic content unavailable in text export] You normally do not set `generated` by hand — generators add it automatically. The locale workflow requires mirrors only for hand-authored pages in configured additional-locale trees, so `generated: true` pages are skipped during translation. ### `pagination_next` - **Type:** `string | null` - **Required:** No - **Default:** Automatically determined by sidebar order Overrides the "Next" page link shown at the bottom of the document. Set to a document path (e.g., `"guides/configuration"`) to link to a specific page, or set to `null` to hide the next link entirely. ```mdx --- title: Final Step pagination_next: null --- ``` ### `pagination_prev` - **Type:** `string | null` - **Required:** No - **Default:** Automatically determined by sidebar order Overrides the "Previous" page link shown at the bottom of the document. Set to a document path (e.g., `"getting-started/introduction"`) to link to a specific page, or set to `null` to hide the previous link entirely. ```mdx --- title: Getting Started pagination_prev: null --- ```