/src/content/CLAUDE.md

CLAUDE.md at /src/content/CLAUDE.md

Path: 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 Claude/Codex resource generators own their overview and category index.mdx targets in the default content directory and every configured locale directory. They generate localized indexes from the resource.* translations, so do not create hand-written locale stubs.

• If an authored file already occupies one of those generator target paths, the generator refuses to overwrite it; it does not silently replace the file. Remove or rename the authored index, then express its title, description, and labels through ZudoDocConfig.translations.

• Claude/Codex resource 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; the legacy resource prefixes are not package or showcase defaults.

Navigation Structure

Navigation is filesystem-driven — directory structure becomes sidebar navigation.

• 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