/packages/create-zudo-doc/CLAUDE.md

CLAUDE.md at /packages/create-zudo-doc/CLAUDE.md

Path: packages/create-zudo-doc/CLAUDE.md

create-zudo-doc

CLI scaffold tool for creating new zudo-doc documentation sites. Generates a project with configurable features, color schemes, and i18n support.

Architecture

The generator uses an additive composition approach:

Copy a minimal base template (templates/base/) — core files with injection anchors
Generate zfb.config.ts, settings.ts, package.json programmatically
Compose selected features — copy feature files + inject code into shared files at anchor points
Clean up unused anchors

This replaces the old "copy everything then strip" approach. Features are added, not removed — so dead code cannot remain.

Key Files

File	Role
`src/scaffold.ts`	Orchestrates the scaffold pipeline: copy base, generate configs, compose features
`src/compose.ts`	Composition engine: injection system, anchor cleanup, feature resolution
`src/features/*.ts`	Feature modules defining injections for each optional feature (15 modules)
`src/zfb-config-gen.ts`	Programmatic `zfb.config.ts` generator — S5b: now emits a thin preset-based config that spreads `zudoDocPreset()` from `@takazudo/zudo-doc/preset`; feature-agnostic (same output for all feature combinations)
`src/settings-gen.ts`	Generates `src/config/settings.ts` with user-chosen options
`src/claude-md-gen.ts`	Generates the per-project `CLAUDE.md` for the scaffolded site
`src/preset.ts`	Resolves the user-chosen preset into a concrete feature set
`src/constants.ts`	Feature definitions, color scheme lists, light-dark pairings
`src/utils.ts`	Shared utilities (patchFile, patchDefaultLang, getSecondaryLang)
`src/cli.ts`	CLI argument parsing (commander)
`src/api.ts`	Programmatic API (`createZudoDoc()`)
`src/prompts.ts`	Interactive prompts (inquirer)
`src/index.ts`	Entry point

Template Directories

Directory	Role
`templates/base/`	Minimal project with injection anchors (post-cutover: only `.tsx`, `.ts`, `.css`, `.json` — no `.astro`)
`templates/features/*/files/`	Feature-specific files copied when a feature is selected

Injection Anchors

The files shipped with anchors in templates/base/ today are:

src/styles/global.css — 3 anchors (@slot:global-css:imports, @slot:global-css:theme-tokens, @slot:global-css:feature-styles)
pages/_mdx-components.ts — anchors consumed by the imageEnlarge feature
pages/lib/_body-end-islands.tsx — anchors consumed by the tauri and designTokenPanel features
src/config/settings-types.ts — replace-range anchors (@slot:settings-types:trigger-names:start/:end) consumed by the designTokenPanel feature to inject "design-token-panel" into HeaderRightTriggerName

The ANCHOR_FILES list in src/compose.ts is the source of truth for which files are anchor-cleaned after composition. Feature-specific files are copied wholesale from templates/features/<name>/files/; no anchor injection into doc-layout/header is required post-zfb-cutover.

src/compose.ts ANCHOR_LINE_RE accepts JSX-comment ({/* @slot:… */}), block-comment, line-comment, HTML-comment, and shell-comment forms so anchors work across .tsx, .ts, and .css.

Testing

Unit tests

pnpm test

Runs vitest tests in src/__tests__/.

Generator CLI integration tests

Two Claude Code skills test the full scaffold-build-run cycle:

/l-generator-cli-tester <pattern> — Test a single generation pattern
/l-run-generator-cli-whole-test — Run all 9 patterns, fix bugs, verify everything

Test patterns

Pattern	Description
`barebone`	Everything OFF — minimal project
`search`	Only search enabled
`i18n`	Only i18n enabled
`sidebar-filter`	Only sidebar filter enabled
`claude-resources`	Only Claude Resources enabled
`design-token-panel`	Only design token panel enabled (API only, no CLI flag)
`light-dark`	Light-dark color scheme mode
`lang-ja`	Japanese as default language
`all-features`	Everything ON

Always rebuild the CLI before testing:

pnpm build

Adding a New Feature

When adding a feature to the main zudo-doc project that the generator should support:

src/constants.ts — Add feature to FEATURES array if it needs a CLI flag
src/features/<name>.ts — Create a feature module defining injections for shared files
src/features/index.ts — Register the feature module
templates/features/<name>/files/ — Add feature-specific files to copy (use .tsx for components, .ts for utilities — no .astro)
src/scaffold.ts — Add dependencies in generatePackageJson() if needed
packages/zudo-doc/src/preset.ts — If the feature introduces a new plugin or collection, add the settings-driven logic to zudoDocPreset(). The generated zfb.config.ts is a thin preset-based file (S5b #2329) — it does NOT need updating for features that are settings-driven (the preset reads the new settings.* field directly). Only update src/zfb-config-gen.ts if the generated config shape itself must change (rare).
src/settings-gen.ts — Add the setting field to generated settings.ts
src/__tests__/scaffold.test.ts — Update tests

After changes, run /l-update-generator to verify no drift remains between the main project and the generator.

View source on GitHub