A zudo-doc project is configured through one file: the root **`zfb.config.ts`**. It calls `zudoDoc()` with the fields you want to change; every other setting falls back to a documented default. ```ts title="zfb.config.ts" import { defineConfig } from "zfb/config"; import { zudoDoc } from "@takazudo/zudo-doc/config"; export default defineConfig( zudoDoc({ siteName: "My Docs", // …only the fields you chose; everything has a documented @default. }), ); ``` `zudoDoc()` merges your fields over the package defaults per field (you win), supplies the package data defaults (frontmatter schema, directive vocabulary, translations, color schemes, tag vocabulary) unless you override them, and returns a **complete `ZfbConfig`** — you spread nothing. [Dynamic content unavailable in text export] The `ZudoDocConfig` type is the single source of truth for this reference. Every field carries a `@default` JSDoc annotation that shows on IDE hover; the tables below mirror those defaults verbatim. When this page and the type disagree, the type wins. [Dynamic content unavailable in text export] The defaults here are the **package defaults** a fresh `create-zudo-doc` project inherits. This showcase enables far more (most features on, i18n, a full header nav) by passing those fields explicitly — do not read the showcase's rich config as the default baseline. ## Home page ### home Homepage layout and optional Markdown introduction, applied to `/` and locale-prefixed homes such as `/ja/`. Default: `{ wide: false, introMarkdown: "", sitemapHeading: "" }` | Field | Type | Purpose | |---|---|---| | `wide` | `boolean` | Widen the outer page container for a larger category grid; defaults to `false`. | | `introMarkdown` | `string` | Optional prose below the logo, title, short tagline and navigation. | | `sitemapHeading` | `string` | Plain-text heading above the existing documentation tree. Blank uses the translated default. | Use `siteDescription` for the short tagline and existing metadata uses; `locales..description` overrides the tagline. Use `introMarkdown` for longer prose. It does not replace metadata or the tagline. Keep [homeExtras / extras](https://zudo-doc.takazudomodular.com/docs/reference/host-chrome-bindings) for inline navigation additions in the slash-separated links row; they are not a prose slot. #### Markdown-first example Edit `zfb.config.ts`; the scaffold's root page can keep its one-line package re-export. The introduction and heading are serializable strings, so a configuration editor can store them without callbacks or executable JavaScript. Fresh scaffolds leave the introduction empty; this showcase's example content is not copied into new projects. ```ts title="zfb.config.ts" import { defineConfig } from "zfb/config"; import { zudoDoc } from "@takazudo/zudo-doc/config"; export default defineConfig( zudoDoc({ siteName: "My Docs", siteDescription: "A short guide to our project.", home: { wide: false, introMarkdown: `## Start here Learn the **essentials**, then explore the reference. - [Getting started](docs/getting-started/) - [Configuration](docs/guides/configuration/) > [!TIP] > Keep the introduction focused on your readers' first steps.`, sitemapHeading: "Browse the guides", }, locales: { ja: { label: "JA", dir: "src/content/docs-ja", description: "プロジェクトの使い方をまとめたガイド。", introMarkdown: `## はじめに **基本的な使い方**を学んでから、リファレンスへ進めます。 - [はじめに](docs/getting-started/) - [設定](docs/guides/configuration/) > [!TIP] > 読者が最初に必要とする情報に絞って紹介しましょう。`, sitemapHeading: "ガイドを探す", }, }, }), ); ``` #### Locale precedence and no-description example Each defined `locales..introMarkdown` or `sitemapHeading` overrides its corresponding `home` field. Omit a locale field to inherit the home value. An explicit empty introduction disables fallback; whitespace-only content also renders nothing. These rules are independent of the locale's short `description`. A blank resolved `sitemapHeading` restores the translated default: “Explore the documentation” in English and “ドキュメントを探す” in Japanese. It does not hide the heading. A blank locale heading restores that locale's default even when the global heading is customized. For a home without long description prose, use this configuration. The logo, title, tagline and navigation remain; there is no prose wrapper or upper separator, and exactly one separator appears before the independent sitemap H2. To hide the short tagline too, clear `siteDescription` and any locale `description` separately. ```ts home: { introMarkdown: "", sitemapHeading: "" }, locales: { ja: { label: "JA", dir: "src/content/docs-ja", introMarkdown: "", sitemapHeading: "", }, }, ``` #### Supported Markdown and safe restrictions The introduction uses the standard Markdown/GFM pipeline and shared non-heading typography, with the following field-specific limits. See [Markdown features](https://zudo-doc.takazudomodular.com/docs/markdown-features) for detail-page examples; executable MDX components shown there are not accepted in this string. | Content | Homepage introduction behavior | |---|---| | Paragraphs, emphasis, bold, deletion and line breaks | Supported. | | Ordered, unordered, nested and task lists | Supported; task checkboxes retain their checked/disabled state. | | Links, reference links and images | Supported with safe URLs; images are responsive. No filesystem dimension lookup or asset-viewer remapping. | | Quotes and GitHub alerts | Supported; use `> [!TIP]` and other GitHub alert markers. | | Inline and fenced code | Supported with production semantic highlighting; code examples stay inert and wide fences scroll internally. | | Tables and thematic breaks | Supported; table alignment is retained and wide tables scroll internally. | | Ruby | The non-executable `{base}^{reading}` syntax is supported. | | Mermaid | Diagram fences use the existing Mermaid initialization when `mermaid: true`; otherwise they remain ordinary code fences. | | Math | Dollar notation stays literal, including with `math: true`; JSX `MathBlock` is unavailable here. | | Directives, transclusion and filesystem includes | Rejected even when enabled for document pages; the introduction has no document source path. | | Raw HTML, JSX, MDX expressions, import/export and YAML frontmatter | Rejected with diagnostics, never executed. Inline code and fences may display them as examples; ordinary non-MDX braces stay inert text. Initial paragraph import/export statements are reserved. | | Code tabs, advanced fence enrichment, heading markers and reading-time/TOC exports | Not enabled; ordinary fences are supported without promising component parity for advanced metadata. | Invalid source, unsafe URLs or unsupported generated markup fail the build with a `home.introMarkdown` diagnostic. Nonblank introductions require the `@takazudo/zfb-md-wasm` peer used by the server/build renderer; blank introductions do not load it. #### Links and images Author homepage URLs, not source-file links: unlike links inside MDX documents, `.md` and `.mdx` extensions are not rewritten. Relative URLs resolve against the active localized homepage with a trailing slash. For example, with base `/manual/` on the Japanese homepage, `docs/getting-started/` resolves to `/manual/ja/docs/getting-started/`, while `/docs/getting-started/` resolves to `/manual/docs/getting-started/`. Root-relative URLs receive the base once and preserve explicit locale prefixes. Use `/img/logo.svg` for a shared root asset; `img/logo.svg` targets the active locale directory. HTTP and HTTPS links/images are allowed, and links also allow `mailto:` and `tel:`. Fragments stay fragments, spaces in paths are encoded, and `..` follows normal URL resolution and can leave the base. Protocol-relative URLs, `data:`, `javascript:`, `vbscript:`, control characters and backslashes are rejected. #### Compact layout and headings Identity and prose share a centered, fixed **60rem maximum width** (960 CSS px at the standard 16px root size), shrinking to the available space and respecting text-size changes. There is no introduction width option. The logo stays 320 CSS px with a 1200:630 aspect ratio and a 100% maximum width. Desktop places the logo left of left-aligned identity text; mobile stacks and centers the identity. Prose stays left-aligned, and long titles, taglines and links wrap. With an introduction, full content-width separators surround the padded prose, followed by a separate sitemap H2 and the existing documentation tree. When tags are enabled, the same separator precedes the Tags heading. The separators follow the outer page container, not the 60rem inner cap. `home.wide: true` still widens that outer container and category grid; its behavior is unchanged. Compared with detail-page headings, compact headings are plain bold text without borders, gradients or hash decorations. H1 Markdown becomes H2 to retain one page H1, and introduction headings never enter the documentation TOC. H2 shares the home section-heading style used by the sitemap and Tags headings — `text-title` (1.4rem by default) at line-height 1.25, with any theme-pack H2 rules, counters or bars removed; H3 uses 1.125rem, H4 1rem, and H5/H6 0.9375rem; body text uses 1rem/1.75. Normal flow gaps are 1rem and heading-adjacent gaps 0.5rem, with section gaps of 1.75rem for H2, 1.5rem for H3, and 1.25rem below that. The first child has no top gap. ### siteTreeNavIgnore Top-level category slugs to hide from the package-owned home-page category grid on `/` and locale-prefixed home pages such as `/ja`, and from the `` / `` MDX tags. This does not affect header nav, sidebar, search, or sitemap. ```ts title="zfb.config.ts" export default defineConfig( zudoDoc({ siteName: "My Docs", siteTreeNavIgnore: ["inbox", "develop"], }), ); ``` The package previously hard-coded `["inbox", "develop"]` for this showcase's own need. The package default is now `[]`; set this field when your site needs to hide categories. Type: `string[]` · Default: `[]` ### siteTreeNavSecondary Top-level category slugs to move out of the package-owned home-page category grid on `/` and locale-prefixed home pages such as `/ja`, and into a compact secondary row directly under it. Each listed category renders as a small chevron link with its label, and the row follows the array order rather than the grid's category order. Use it for system-level categories that should stay reachable from the home page without competing with the primary reading paths. ```ts title="zfb.config.ts" export default defineConfig( zudoDoc({ siteName: "My Docs", siteTreeNavSecondary: ["changelog", "claude", "codex"], }), ); ``` - A slug that matches no top-level category is skipped. - A slug that is also listed in [`siteTreeNavIgnore`](https://zudo-doc.takazudomodular.com/docs/guides/configuration#home-page-sitetreenavignore) is hidden entirely — `siteTreeNavIgnore` wins. - A category without its own page ([`category_no_page: true`](https://zudo-doc.takazudomodular.com/docs/guides/frontmatter#fields-category_no_page)) has no link target, so it stays in the grid and a development warning is logged. - An empty list renders no secondary row. This affects only the home page. The `` / `` MDX tags ignore it, and header nav, sidebar, search, and sitemap are unchanged. Type: `string[]` · Default: `[]` ## Identity and URLs ### siteName Site name shown in the header and metadata. Page titles render as `{page title} | {siteName}`. The one field you almost always set. Default: `"Docs"` ### siteDescription Site description used in metadata (``, llms.txt). Default: `""` ### logo Home-hero logo. `"auto"` (the default) renders a generated deterministic SVG seeded by `siteName` — a framed "decorated plate" mark that adapts to light/dark automatically, so a fresh project gets a presentable hero with no asset work. Set a path string (e.g. `"/img/logo.svg"`) to render your own asset as a theme-adaptive CSS mask, or `false` to hide the logo block entirely. Run `npx zudo-doc eject logo` to materialize the generated mark as a real file: it writes `public/img/logo.svg` and flips this field to `"/img/logo.svg"`, so you own an editable asset — tweak it, replace it, or reuse it elsewhere (e.g. for OGP) — instead of the request-time generated default. See [Customizing → Rung 5](https://zudo-doc.takazudomodular.com/docs/reference/customizing#rung-5-%E2%80%94-ejecting-a-component) for the CLI flags. `logo: ""` throws a `TypeError` at config resolution instead of silently rendering a CSS mask of an empty path — pass `false` to hide the logo, or omit the field for the default. Default: `"auto"` ### favicon The `` set emitted into every page's ``. Omit it and you get the four-file convention a fresh `create-zudo-doc` project ships in `public/`: `favicon.svg`, `favicon.ico` (`sizes="any"`), `favicon-32x32.png`, `favicon-16x16.png`, in that order. Type: `string | FaviconConfig | false` · Default: `undefined` (the four-link set above) | Value | What it emits | |-------|---------------| | omitted | The four-link default | | `"auto"` | One inline SVG `data:` URL icon generated from `siteName` — no asset files needed | | any other string | One link to that path, with `type` inferred from the file extension | | a `FaviconConfig` object | Only the slots you supply, always in `svg` → `ico` → `png32` → `png16` order | | `false` | No favicon links at all | | `""` | Throws a `TypeError` at config resolution — see below | **The empty string is rejected, not emitted.** Per the HTML spec an empty `href` resolves to the *current document*, so `favicon: ""` would silently make every page fetch its own HTML as a "favicon" — a wasted request and a garbage tab icon. `zudoDoc({ favicon: "" })` throws a `TypeError` naming the field instead; pass `false` for no favicon links, or omit the field for the default four-link set. The same rejection applies to an empty-string `FaviconConfig` slot (e.g. `favicon: { ico: "" }`) — the error names the specific slot (`favicon.ico`). An empty *object* (`favicon: {}`, no slots at all) is unaffected and still validly emits nothing. Only the exact empty string is rejected — a whitespace-only value like `" "` is passed through as-is. **The default is a convention, not a check.** It emits all four links whether or not the files exist — so a project whose `public/` has no `favicon.ico` still ships `` on every page, and every visitor's browser console logs a 404 for it. Supplying only the slots you actually have is the fix: ```ts title="zfb.config.ts" export default defineConfig( zudoDoc({ siteName: "My Docs", // No favicon.ico in public/, so no ico link — and no console 404. favicon: { svg: "/favicon.svg", png32: "/favicon-32x32.png", png16: "/favicon-16x16.png", }, }), ); ``` `FaviconConfig` is `{ svg?: string; png32?: string; png16?: string; ico?: string }`. Every key is optional, the order you write them in does not matter (emission order is fixed), and `{}` emits nothing at all — the same result as `false`. A plain string collapses the set to a single link and infers `type` from the extension: `.svg`, `.png`, `.ico`, `.jpg` / `.jpeg`, `.gif`, `.webp`, `.avif`. Anything else omits `type` and lets the browser sniff. A `?query` or `#hash` suffix is ignored when inferring, so `"/icon.svg?v=2"` still gets `type="image/svg+xml"`. ```ts favicon: "/icon.png", // one link, type="image/png" favicon: false, // no favicon links at all ``` `favicon: "auto"` needs no asset files at all: it emits one SVG favicon as an inline `data:` URL, generated deterministically from `siteName` with the same seeded glyph as [`logo: "auto"`](https://zudo-doc.takazudomodular.com/docs/guides/configuration#identity-and-urls-logo), so the hero logo and the browser-tab icon show the same mark. The favicon variant is a square, opaque, fixed light-palette plate — a tab icon cannot follow the page's color mode the way the masked hero logo does. [Dynamic content unavailable in text export] SVG favicon support is still uneven across browsers (Safari most notably). `"auto"` degrades to the browser's default blank icon rather than a broken one, but a project that wants maximal coverage should ship real `.ico` / `.png` files and use the object form. Href values starting with `/` are prefixed with the configured [`base`](https://zudo-doc.takazudomodular.com/docs/guides/configuration#identity-and-urls-base), so `"/favicon.svg"` resolves to `/pj/my-site/favicon.svg` on a sub-path deployment. Anything else — an absolute `https://…` URL, a `data:` URL — is emitted verbatim. [Dynamic content unavailable in text export] [`head.alternateLinks`](https://zudo-doc.takazudomodular.com/docs/guides/configuration#identity-and-urls-head) cannot replace this set. Those entries render **after** the favicon block, so a `{ rel: "icon" }` entry there only appends one more link — it can never remove or override one of these. `favicon` is the only way to change what the set contains. ### siteUrl Canonical site origin (e.g. `"https://example.com"`) for sitemap / canonical / `og:url`. Empty = not set. Default: `""` ### base Public URL sub-path prefix mounted in front of every absolute asset URL (e.g. `"/pj/my-site/"`). `"/"` = root-mounted. All internal links (sidebar, nav, prev/next, search) are prefixed automatically. Default: `"/"` [Dynamic content unavailable in text export] Inline markdown links in MDX (e.g. `[text](/docs/some-page)`) are **not** rewritten for a non-root base — use relative links in content instead. ### trailingSlash Append a trailing `/` to extensionless internal hrefs. Default: `false` See [Trailing-Slash Policy](https://zudo-doc.takazudomodular.com/docs/develop/trailing-slash-policy) for how the rule splits between build time and the deployment host. ### minifyHtml Minify production HTML output from `zfb build`. Set `false` for readable output while debugging. Default: `true` ### githubUrl GitHub repository URL shown in the header (via the `github-link` header item), or `false` to omit. Type: `string | false` · Default: `false` ### editUrl "Edit this page" link base, or `false` to omit. The full URL is `editUrl + contentDir + "/" + entryId`. Type: `string | false` · Default: `false` ### noindex Add `noindex,nofollow` to every page (for internal docs). Default: `false` See [Avoid Robots Indexing](https://zudo-doc.takazudomodular.com/docs/guides/avoid-robots-indexing). ### head Site-wide custom `` extras (preconnect / preload / stylesheets / meta / alternateLinks). Omit to emit nothing extra. Type: `SiteHeadConfig` · Default: `undefined` ### metaTags `` / OpenGraph / Twitter-card emission toggles. Default: `{ description: true, keywords: false, ogImage: false, ogSiteName: true, twitterCard: false }` | Property | Type | Description | |----------|------|-------------| | `description` | `boolean` | Emit `` | | `keywords` | `string \| false` | `` value, or omit | | `ogImage` | `string \| false` | Path for `og:image` / `twitter:image`, or omit | | `ogSiteName` | `boolean` | Emit `og:site_name` | | `twitterCard` | `"summary" \| "summary_large_image" \| false` | Twitter Card type, or omit the block | | `twitterSite` | `string` (optional) | `twitter:site` handle | | `twitterCreator` | `string` (optional) | `twitter:creator` handle | ### sitemap Emit a sitemap route. Default: `false` **Set `sitemap: true` if you want one.** At the default `false`, no `/sitemap.xml` route is emitted at all — the URL 404s. Setting `siteUrl` is not enough on its own: configuring `siteUrl` only for canonical / `og:url` is a perfectly normal setup, so nothing is inferred from it and no build-time warning nudges you. This reference is where that contract lives. Serving nothing is deliberate. An empty `` at a well-known URL is not a neutral placeholder — it is a positive assertion to crawlers that the site has no indexable URLs, which is worse than the URL simply not existing. The generated `robots.txt` already drops its `Sitemap:` line in this state, so the two artifacts now agree instead of contradicting each other. Earlier versions did emit the empty ``; they no longer do. The gate lives in the package's route injection (`packageOwnedRoutes`, on by default). A project that hand-wires its own `pages/sitemap.xml.tsx` sits outside it and keeps whatever that page returns — and if that page re-exports the package entrypoint while `sitemap` is `false`, the build warns and still writes the empty ``. See also the [SEO guide](https://zudo-doc.takazudomodular.com/docs/guides/seo) for how `metaTags` and `sitemap` combine into a complete social-share + search-indexing setup. ### onBrokenMarkdownLinks What to do when a `.md`/`.mdx` link cannot be resolved: `"warn"` logs and continues, `"error"` fails the build, `"ignore"` is silent. Type: `"warn" | "error" | "ignore"` · Default: `"warn"` This setting also governs the post-build existence check for raw `` attributes in rendered HTML. `"error"` reports problems and fails the build, `"warn"` reports and continues, and `"ignore"` skips the scan entirely. The scan checks site-absolute paths beginning with `/`. It strips queries and fragments, decodes URL escapes, and checks for a file in the build output. With `base: "/manual/"`, `/manual/img/logo.svg` maps to `dist/img/logo.svg`. Paths outside that base, missing files, and paths escaping the output directory are reported as broken. External URLs, protocol-relative `//` URLs, schemes such as `data:`, and relative paths are excluded. Comments, script strings, and escaped code examples are not treated as images. `srcset` is not checked. ## Color ### colorScheme Active color scheme name (must exist in `colorSchemes`). The two bundled schemes are `Default Light` and `Default Dark`. Default: `"Default Dark"` ### colorMode Light/dark mode wiring, or `false` for a single fixed scheme. Default: `{ defaultMode: "dark", lightScheme: "Default Light", darkScheme: "Default Dark", respectPrefersColorScheme: true }` | Property | Type | Description | |----------|------|-------------| | `defaultMode` | `"light" \| "dark"` | Light/dark fallback when system following is disabled and no choice is saved | | `lightScheme` | `string` | Scheme used in light mode | | `darkScheme` | `string` | Scheme used in dark mode | | `respectPrefersColorScheme` | `boolean` | Use System as the first-visit choice when no preference is saved | With the default `respectPrefersColorScheme: true`, a first visit with no saved choice starts in **System** and follows the device's light/dark preference. The compact header appearance menu offers **Light**, **Dark**, and **System**; its icon shows the selected preference (sun for Light, moon for Dark, monitor for System), not the next action. The preference is saved in `localStorage` under `zudo-doc-theme` and remains selected after reload. `defaultMode` remains a two-value light/dark fallback. If you set `respectPrefersColorScheme: false`, a first visit with no saved choice uses `defaultMode`; a visitor can still explicitly select System, which continues to follow the device. `colorMode: false` keeps a single fixed scheme and has no appearance menu. ```ts colorMode: false, // single fixed scheme (colorScheme only) ``` See the [Color reference](https://zudo-doc.takazudomodular.com/docs/reference/color) for the ramp-native model and adding a custom scheme (via the `colorSchemes` escape hatch below). ## Theme packs Theme packs are installable design bundles layered **on top of** the color-scheme system above — every pack defines both its light and dark values, so the appearance menu keeps working on any pack. See the [Theme Packs reference](https://zudo-doc.takazudomodular.com/docs/reference/theme-packs) for the switcher UI, the theme CLI, and pack authoring. ### themePack Active theme pack slug. `"default"` is the stock zudo-doc look (no pack stylesheet loaded). Must be a member of the resolved `themePacks` list; an unknown slug fails the build loudly. Default: `"default"` ### themePackSwitcher Mount the bottom-right theme-pack switcher flyout (and its browse-all dialog) on every page. Default: `false` ### themePacks Enabled pack slugs, in switcher order — the list order is the switcher's Prev/Next cycle order and the browse-all grid order. `undefined` enables all bundled packs: `"default"` first, then the rest alphabetically. An explicit list is authoritative — it may omit `"default"` and reorder freely; duplicates or unknown slugs fail the build loudly. Default: `undefined` ```ts themePacks: ["default", "foundry"], ``` ## Content and i18n ### docsDir Directory (project-root-relative) holding the default-locale docs. Default: `"src/content/docs"` ### entryDocSlug Route slug of the doc page the [versions page](https://zudo-doc.takazudomodular.com/docs/guides/versioning#versions-listing-page) links to as the "latest docs" entry point (and each past version's docs link). No leading or trailing slashes — e.g. `"getting-started"` or `"overview/getting-started"`. Not validated at runtime; an invalid slug simply 404s. Default: `"getting-started"` ### dateFormat Date-display format. `"locale"` keeps the built-in `Intl` rendering; anything else is a token pattern. Type: `DateFormatSetting` · Default: `"locale"` zudo-doc renders dates in five distinct **shapes**, so the setting is keyed by shape — called a *role* — rather than by call site. Nobody wants the pager date to differ from the header date, but a compact card stamp genuinely differs from a full date line. | Role | Default (`en`) | Default (`ja`) | Where it appears | |---|---|---|---| | `full` | `Aug 22, 2026` | `2026年8月22日` | H1 date line, git metainfo, pager, asset page, revision history, note-tray list and timeline, ungrouped site-tree rows | | `monthDay` | `Aug 22` | `8月22日` | Note-tray card grid | | `year` | `2026` | `2026年` | Note-tray card grid, year-group headings | | `yearMonth` | `2026 August` | `2026年8月` | Note-tray, sidebar and site-tree month-group headings | | `numericMonthDay` | `08-22` | `08-22` | Sidebar tray rows, site-tree grouped rows | `numericMonthDay` is deliberately locale-insensitive at its default: it is a compact sort-aligned stamp, not prose, so it renders `08-22` in every locale. Give it a pattern and it formats like any other role. [Dynamic content unavailable in text export] Year-group headings in the sidebar and the site tree print the grouping key itself — `2026` in every locale — because a year heading has never gone through a formatter, and routing it through one would silently turn existing Japanese sites into `2026年`. The note-tray card grid does format its year, so a Japanese page shows `2026年` there. Set `year` to a pattern and both surfaces follow it; headings apply the pattern against January 1 of that year, so month or day tokens in a `year` pattern render that boundary date. #### A bare string sets only `full` This is the setting's one real surprise. A bare pattern is shorthand for `{ full: "…" }`, so it changes the H1 date line, the pager and the other `full` surfaces — and leaves card stamps, month headings and sidebar rows exactly as they were: ```ts dateFormat: "YYYY/MM/DD", ``` To change those too, name their roles. #### Roles and per-locale overrides The object form takes the five role keys plus an optional `locales` map keyed by locale code, whose values take the same five keys: ```ts dateFormat: { full: "MM/DD/YYYY", yearMonth: "MM/YYYY", locales: { ja: { full: "YYYY年M月D日" }, }, }, ``` Resolution precedence, evaluated **per role**: 1. `locales[locale][role]` — the per-locale override 2. `[role]` — the top-level role 3. `"locale"` — the built-in `Intl` rendering Per-locale overrides are the point of the object form on a multilingual site: `Aug 22, 2026` and `2026年8月22日` are both correct for their locale, and no single pattern serves both. See [Internationalization](https://zudo-doc.takazudomodular.com/docs/guides/i18n#date-formats-per-locale). #### Supported tokens | Token | Meaning | `2026-08-05` (`en`) | |---|---|---| | `YYYY` | 4-digit year | `2026` | | `YY` | 2-digit year | `26` | | `MMMM` | Full month name (locale-aware) | `August` | | `MMM` | Short month name (locale-aware) | `Aug` | | `MM` | Zero-padded month | `08` | | `M` | Month | `8` | | `DD` | Zero-padded day | `05` | | `D` | Day | `5` | | `[…]` | Literal escape — `[at] YYYY` | `at 2026` | Matching rules worth knowing: - Anything that is not a token passes through literally, so `/`, `-`, `.`, spaces and `年 月 日` need no escaping. - The longest token wins at each position: `YYYY` beats `YY`, and `MMMM` beats `MMM`, `MM` and `M`. - A substituted month name is never rescanned, so `March` and `May` keep their `M`. - An unrecognized run degrades instead of failing the build: `YYYYY` renders the year followed by a literal `Y`, and `dddd` stays `dddd`. - Brackets do not nest — the first `]` closes the escape — and an unmatched `[` is emitted literally while the rest of the pattern still resolves. - `MMM` and `MMMM` produce localized month names for `en`, `ja` and `de` only; every other locale falls back to English names. See [Date formats per locale](https://zudo-doc.takazudomodular.com/docs/guides/i18n#date-formats-per-locale). [Dynamic content unavailable in text export] The token spellings are borrowed from Day.js because they are familiar, but this is a bounded vocabulary, not Day.js compatibility. The eight tokens above and `[…]` escapes are the whole set: there are no weekday, time, quarter, or era tokens and no plugin surface. Everything else is emitted literally. #### Examples A bare pattern — the `full` role in every locale. The H1 date line and pager read `2026/08/22`; card stamps, month headings and sidebar rows are untouched: ```ts title="zfb.config.ts" export default defineConfig( zudoDoc({ dateFormat: "YYYY/MM/DD", }), ); ``` Two roles, every locale. `full` reads `08/22/2026` and `yearMonth` reads `08/2026`; `monthDay`, `year` and `numericMonthDay` stay at `"locale"`: ```ts title="zfb.config.ts" export default defineConfig( zudoDoc({ dateFormat: { full: "MM/DD/YYYY", yearMonth: "MM/YYYY", }, }), ); ``` Per-locale. English pages read `Aug 22, 2026` and Japanese pages `2026年8月22日`; `yearMonth` is overridden on `ja` only, so English keeps its default `2026 August` while Japanese reads `2026年8月`: ```ts title="zfb.config.ts" export default defineConfig( zudoDoc({ dateFormat: { full: "MMM D, YYYY", locales: { ja: { full: "YYYY年M月D日", yearMonth: "YYYY年M月" }, }, }, }), ); ``` #### An object replaces the default wholesale `zudoDoc()` merges your fields over the package defaults at the **top level only**, so a supplied `dateFormat` object replaces the default `"locale"` outright rather than being deep-merged into it. That costs nothing here: the resolver fills every role you leave out with `"locale"` anyway, which is exactly what the default meant. #### What it does not affect `dateFormat` is a display setting. It does not touch the `YYYY-MM-DD` [frontmatter authoring format](https://zudo-doc.takazudomodular.com/docs/guides/frontmatter#fields-date), the machine-readable `datetime` attributes on `