src/content/CLAUDE.md
Doc Content (src/content/)
Before writing or editing any .mdx here, invoke /. 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/ (source: packages/), 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: truein frontmatter are generator-owned; do not hand-edit or translate them.The
docSourcesplugin (this showcase mounts.claude/atclaude/and.codex/atcodex/) owns the section and indexindex.mdxtargets under each mount in the default content directory and every configured locale directory. It generates localized indexes from thedocSources.*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/) are default-locale-only by design — create no locale mirror. This repository currently configures no such prefixes.config/ settings. ts
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/. Typo and wording fixes skip it.
Navigation Structure
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/); 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/. 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 tolib/ learn- chrome. tsx src/(enforced bylib/ learn- * src/)._ _ tests_ _ / editorial- navigation- guide. test. ts Pages ordered by
sidebar_position(ascending)Category index pages (
index.mdx) control category position viasidebar_position; addsidebar_labelfor a custom sidebar name; addcategory_sort_order: "desc"for newest-first ordering; addcategory_no_page: trueto 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 declarescategory_shape: "note-tray"and uses<NoteTrayIndex>. A tray requires a visible routedindex.mdx;note_tray_dated: truerequiresdateon every child (including unlisted children), andnote_tray_sidebaraccepts"index","year", or"month"(the grouped styles require a dated tray).Note-tray order always comes from
sidebar_positionpluscategory_sort_order; rank is derived and must not be authored. Keep positions monotonic withdatein dated trays._category_.jsonstill works but triggers a zfb build warning; preferindex.mdxfrontmatterHeader nav is defined in
src/viaconfig/ settings. ts headerNavwithcategoryMatch