zudo-doc
GitHub repository

Type to search...

to open search from anywhere

src/content/CLAUDE.md

Doc Content (src/content/)

Before writing or editing any .mdx here, invoke /zudo-doc-writing-rules. That skill is the canonical copy of the writing rules — no h1 in content, mandatory sidebar_position, kebab-case file names, no horizontal rules as separators, the frontmatter schema table, the bilingual rule, linking conventions, admonition syntax, and the content-creation workflow. This file keeps only what is not in the skill.

The frontmatter schema itself is package-owned — @takazudo/zudo-doc/docs-schema (source: packages/zudo-doc/src/docs-schema/index.ts), wired in by zudoDoc(). It is not defined in the repo-root zfb.config.ts, which deliberately omits buildDocsSchema.

The one rule to remember without loading the skill

When creating or updating any doc page, update both EN (docs/) and JA (docs-ja/) versions. Keep code blocks and <HtmlPreview> blocks identical — only translate prose. JA mirrors the EN directory tree exactly. Exceptions below.

Bilingual carve-outs

  • Files with generated: true in frontmatter are generator-owned; do not hand-edit or translate them.

  • The docSources plugin (this showcase mounts .claude/ at claude/ and .codex/ at codex/) owns the section and index index.mdx targets under each mount in the default content directory and every configured locale directory. It generates localized indexes from the docSources.* translations, so do not create hand-written locale stubs.

  • If an authored file already occupies one of those target paths, the build fails and names the file; it never silently replaces it. Remove or rename the authored file, then express its title, description, and labels through ZudoDocConfig.translations.

  • Document-source detail files remain in the default content directory and are exposed at other locale routes through body fallback. Do not copy those generated detail files into locale directories.

  • Paths explicitly configured under settings.defaultLocaleOnlyPrefixes (src/config/settings.ts) are default-locale-only by design — create no locale mirror. This repository currently configures no such prefixes.

Adding pages or changing categories

Before adding a page, changing what a page is for, or changing a category, run the placement check in the zudo-doc-navigation-design skill (four questions; a structure review only on evidence of conflict, duplication, a new reader-task cluster, or a findability problem). The full procedure is guides/maintaining-documentation-structure.mdx. Typo and wording fixes skip it.

By default, navigation is filesystem-driven — directory structure becomes sidebar navigation. Re-parenting existing pages without moving their URLs is an advanced chrome-bindings recipe (guides/editorial-navigation.mdx); prefer moving files. Write the intended tree and each destination's behavior before choosing configuration (zudo-doc-navigation-design skill).

  • Learn is one linked umbrella tree (Learn → Guides, Components, Markdown Features with their full subtrees), built by src/lib/learn-chrome.tsx. A header dropdown or a list of section pages never creates a sidebar parent. The Editorial Navigation guide's umbrella helper blocks must stay byte-identical to src/lib/learn-* (enforced by src/__tests__/editorial-navigation-guide.test.ts).

  • Pages ordered by sidebar_position (ascending)

  • Category index pages (index.mdx) control category position via sidebar_position; add sidebar_label for a custom sidebar name; add category_sort_order: "desc" for newest-first ordering; add category_no_page: true to create a non-linked category header (no route/sitemap/search entry)

  • Categories have two shapes: the default nested tree uses <CategoryNav> on its index; a top-level, flat note tray declares category_shape: "note-tray" and uses <NoteTrayIndex>. A tray requires a visible routed index.mdx; note_tray_dated: true requires date on every child (including unlisted children), and note_tray_sidebar accepts "index", "year", or "month" (the grouped styles require a dated tray).

  • Note-tray order always comes from sidebar_position plus category_sort_order; rank is derived and must not be authored. Keep positions monotonic with date in dated trays.

  • _category_.json still works but triggers a zfb build warning; prefer index.mdx frontmatter

  • Header nav is defined in src/config/settings.ts via headerNav with categoryMatch

AI Assistant

Ask a question about the documentation.

Preview theme

Loading theme previews…