zudo-doc
GitHub repository

Type to search...

to open search from anywhere

Document Sources

Created Nov 20, 2026Claude

Publish files that live outside docsDir, such as Claude Code and Codex configuration or any Markdown tree, as generated documentation sections.

Overview

The docSources setting bakes files from outside your content directory into ordinary documentation routes. Each entry is either a bundled preset (Claude Code or Codex configuration) or a custom source that maps any directory you choose. Every entry becomes one top-level section at /docs/<mount>/.

The setting is optional and defaults to []. With no entries nothing is generated, and any output left by an earlier configuration is removed.

zfb.config.ts
export default defineConfig(
  zudoDoc({
    docSources: [
      { id: "claude", preset: "claude-code", root: ".claude" },
      { id: "codex", preset: "codex", root: ".codex" },
    ],
  }),
);

This is the configuration of this showcase. It publishes the repository's .claude/ and .codex/ directories at /docs/claude/ and /docs/codex/.

The package plugin (@takazudo/zudo-doc/plugins/doc-sources) does all filesystem work at build time; zudoDoc() wires it in automatically. The setting itself is plain data.

Preset Entries

FieldTypeDescription
idstringStable source identifier (letters, digits, -, _). Also the default mount
preset"claude-code" | "codex"The bundled preset to expand
rootstringThe agent configuration directory, such as .claude or .codex. It must exist
scanRootstringOptional directory scanned for instruction files (and, for Codex, .agents/skills). Defaults to the project root
mountstringOptional top-level route segment. Defaults to id

A preset expands into ordinary mappings and runs through the same pipeline as a custom source. Sections whose directory is absent are skipped; only the preset root itself is required.

Claude Code preset

SectionRouteSource
Instructions/docs/<mount>/instructions/Every CLAUDE.md below scanRoot
Commands/docs/<mount>/commands/<root>/commands/**/*.md
Skills/docs/<mount>/skills/<root>/skills/*/SKILL.md and the files beside it
Agents/docs/<mount>/agents/<root>/agents/**/*.md

The root CLAUDE.md is the Instructions landing page. A nested packages/core/CLAUDE.md becomes /docs/<mount>/instructions/packages/core/ and is titled by its path.

Codex preset

SectionRouteSource
Instructions/docs/<mount>/instructions/Every AGENTS.md and AGENTS.override.md below scanRoot
Config/docs/<mount>/config/config.toml, config.toml.example, and *.config.toml profiles in root
Agents/docs/<mount>/agents/<root>/agents/*.toml
Hooks/docs/<mount>/hooks/<root>/hooks.json and every file below <root>/hooks/
Rules/docs/<mount>/rules/<root>/rules/*.rules
Skills/docs/<mount>/skills/<root>/skills/*/SKILL.md and <scanRoot>/.agents/skills/*/SKILL.md

Both presets skip hidden directories, node_modules, dist, out, public, worktrees, __inbox and test-results during the instruction scan.

A skill becomes one page at /docs/<mount>/skills/<name>/. It lists the skill's file structure, and other Markdown files in the skill directory (for example references/checklist.md) become unlisted sibling pages such as references-checklist, linked from the skill page.

Custom Sources

A custom source publishes any directory tree through explicit mappings:

FieldTypeDescription
idstringStable source identifier. Also the default mount
titlestringTitle of the source's landing page
mountstringOptional top-level route segment. Defaults to id
mappingsarrayOne or more mappings (below)

Each mapping selects files from one root:

FieldTypeDescription
idstringMapping identifier, unique within the source
rootstringDirectory to read from
includestring[]Glob patterns relative to root
excludestring[]Optional glob patterns removed from include
tostringOptional route subtree below the mount, such as "handbook" or "guides/ops". Defaults to the mount root
format"markdown" | "code" | "skill"How each selected file is rendered
missing"error" | "skip"What to do when root does not exist. Defaults to "error"
assets{ include, exclude? }Optional non-document files (images, attachments) to publish

Relative paths resolve from the project root. Absolute paths and ~/ paths also work; ~user forms are rejected. Glob patterns must stay relative to the mapping root.

The three formats:

  • markdown renders Markdown with its frontmatter. title (or name), the first # heading, or the file name becomes the page title; description is kept; other scalar frontmatter fields are shown as a table.

  • code shows the whole file in a highlighted code block titled by its file name. A leading comment line becomes the description.

  • skill treats each selected SKILL.md as a skill package, as the presets do.

Example: a sibling handbook and personal notes

zfb.config.ts
docSources: [
  {
    id: "handbook",
    title: "Handbook",
    mappings: [
      { id: "all", root: "../handbook", include: ["**/*.md"], format: "markdown" },
    ],
  },
  {
    id: "notes",
    title: "Notes",
    mount: "my-notes",
    mappings: [
      { id: "notes", root: "~/notes", include: ["*.md"], to: "journal", format: "markdown" },
    ],
  },
],

With ../handbook/README.md and ../handbook/guides/setup.md, and ~/notes/daily.md, the build produces:

/docs/handbook/                 ← ../handbook/README.md
/docs/handbook/guides/          ← synthesized index
/docs/handbook/guides/setup/    ← ../handbook/guides/setup.md
/docs/my-notes/                 ← synthesized index
/docs/my-notes/journal/         ← synthesized index
/docs/my-notes/journal/daily/   ← ~/notes/daily.md

Example: a Grok-style layout

Illustrative layout

The directory layout below is a synthetic example used to show how a custom mapping handles an unfamiliar tool. It is not a verified description of how Grok, or any other tool, actually stores its configuration. Check your tool's own documentation and adjust the patterns.

Suppose a tool keeps a rules file, a folder of prompts and a JSON settings file in .grok/:

.grok/
├── GROK.md
├── prompts/
│   └── review.md
└── settings.json

Two mappings publish the Markdown as pages and the JSON as source code:

zfb.config.ts
docSources: [
  {
    id: "grok",
    title: "Grok",
    mappings: [
      {
        id: "rules",
        root: ".grok",
        include: ["GROK.md", "prompts/**/*.md"],
        to: "rules",
        format: "markdown",
      },
      { id: "settings", root: ".grok", include: ["*.json"], to: "settings", format: "code" },
    ],
  },
],

The result is /docs/grok/rules/grok/, /docs/grok/rules/prompts/review/ and /docs/grok/settings/settings-json/, plus synthesized indexes for /docs/grok/, /docs/grok/rules/, /docs/grok/rules/prompts/ and /docs/grok/settings/. A link from GROK.md to prompts/review.md is rewritten to the generated page.

Routes and Landing Pages

Every page lives at /docs/<mount>/<section>/<relative path>/, where the section is the mapping's to (or a preset section) and the relative path follows the file's location below the mapping root. File and directory names are lower-cased and non-alphanumeric runs become -. Markdown extensions are dropped, while a code file keeps its extension in the slug (settings.json becomes settings-json).

  • In a markdown or skill mapping, index.md, index.mdx and README.md become the landing page of their directory.

  • Index pages are synthesized only for directories that no mapped document owns. A synthesized index lists its children with <CategoryNav>.

  • Two files that resolve to the same route fail the build and name both files. Rename one, or change a mapping's to or a source's mount.

  • Routes depend only on the mount, the mapping and the file's relative path. Editing content does not change them, and moving a source root keeps them as long as the relative layout stays the same.

Source sections are placed at sidebar position 900 and above, in configuration order.

Header Navigation

Each mount is an ordinary top-level category, so header items use categoryMatch with the mount:

zfb.config.ts
headerNav: [
  { label: "Claude", path: "/docs/claude", categoryMatch: "claude", versioned: false },
  { label: "Codex", path: "/docs/codex", categoryMatch: "codex", versioned: false },
],

Document sources are never written into versioned snapshots, so set versioned: false on their header items. See Header Navigation.

Links between mapped files are rewritten to the generated pages, including reference-style links, images, URL-encoded names and angle-bracket destinations. Query strings and fragments are kept. A link to a directory resolves to its README.md, index.md, index.mdx, SKILL.md, CLAUDE.md or AGENTS.md when that file is mapped.

Inline code and fenced code are never changed. External URLs and in-page fragments are kept as they are. A link to a file that is not mapped is replaced by its readable text, and the build prints a warning naming the target.

Files selected by a mapping's assets are copied to public/doc-sources/<mount>/<section>/... and links to them point at the copy, including the site base.

Generated Pages

Generated pages carry generated: true and provenance fields:

generated: true
doc_source: claude
doc_source_mapping: commands
doc_source_path: deploy.md

doc_source_path is relative to the mapping root. Generated pages show no document history and no view-source link. Absolute source paths, home directories and the private configuration never reach the rendered page or the browser payload.

Output Ownership

The plugin records every file it writes in a build-local manifest at .zfb/doc-sources/manifest.json. Each run:

  • builds the complete plan first, so a failed run (a missing required root, a route collision, an invalid entry) leaves the previous output untouched;

  • writes only files whose content changed;

  • removes previously generated files that are no longer planned, as long as they are unchanged since generation;

  • never overwrites an authored file. If a planned output path already holds a file the manifest does not list, the build fails and names the file;

  • reports a hand-edited generated file. Overwriting it fails the build; a stale edited file is kept and released from ownership with a warning.

Reconciliation runs even when docSources is [], so removing an entry cleans up its output. Edit the source files, not the generated pages.

Locales

Detail pages are written only to the default content directory. Other locales show them through body fallback, without the untranslated-page banner.

Section and index pages are generated in every configured locale directory. Preset labels come from the docSources.* translation keys, which ship in English and Japanese and can be overridden through ZudoDocConfig.translations:

zfb.config.ts
translations: {
  ja: {
    "docSources.claudeCode.description": "チーム用 Claude Code リファレンス。",
    "docSources.section.skills.label": "スキル集",
  },
},

Custom source titles and section labels come from the configuration (title, the last segment of to, or the directory name). Paths listed in defaultLocaleOnlyPrefixes are respected: no locale index is generated below them. See Internationalization.

Discovery follows a symlink only when its real target lies inside one of the configured roots. To publish a shared tree reached through a symlink, configure its target as a mapping root. Broken symlinks and cycles are skipped with a warning.

The content directories, public/doc-sources/, the build output and .zfb/ are never scanned, even when reached through an alias, so generated output never feeds back into discovery.

Development

zfb's dev server does not regenerate content files from outside sources, so run the package's watcher beside it:

zudo-doc sources watch

zudo-doc is the bin of @takazudo/zudo-doc. The watcher reuses the configuration the build plugin recorded and regenerates on file additions, edits, deletions and renames, new directories, and roots that appear or disappear. Runs are debounced, and a failed run keeps the previous output. In this repository pnpm dev starts it automatically.

Migrating from claudeResources and codexResources

docSources replaces the former claudeResources and codexResources settings. There are no compatibility shims: the old keys are removed, and the old routes are not redirected.

zfb.config.ts
// Before
claudeResources: { claudeDir: ".claude" },
codexResources: { codexDir: ".codex" },

// After
docSources: [
  { id: "claude", preset: "claude-code", root: ".claude" },
  { id: "codex", preset: "codex", root: ".codex" },
],

A former scanRoot maps to the preset's scanRoot. With the mounts above, the routes move as follows:

Old routeNew route
/docs/claude-md/…/docs/claude/instructions/…
/docs/claude-commands/…/docs/claude/commands/…
/docs/claude-skills/…/docs/claude/skills/…
/docs/claude-agents/…/docs/claude/agents/…
/docs/codex-agents-md/…/docs/codex/instructions/…
/docs/codex-config/…/docs/codex/config/…
/docs/codex-agents/…/docs/codex/agents/…
/docs/codex-hooks/…/docs/codex/hooks/…
/docs/codex-rules/…/docs/codex/rules/…
/docs/codex-skills/…/docs/codex/skills/…

Update headerNav items whose categoryMatch relied on the old claude-* or codex-* directories, and any defaultLocaleOnlyPrefixes entries that list old routes. Rename the old resource.* translation overrides to the matching docSources.* keys.

One-time cleanup of old generated output

The old generators wrote gitignored output into the default content directory and each locale directory. The new engine does not own those files and refuses to overwrite them under claude/ and codex/. Before the first build, list the old generated files for review:

for dir in src/content/docs src/content/docs-ja; do
  for name in claude claude-agents claude-commands claude-md claude-skills \
    codex codex-agents codex-agents-md codex-config codex-hooks codex-rules codex-skills; do
    [ -d "$dir/$name" ] && grep -rl '^generated: true' "$dir/$name"
  done
done > old-generated.txt
cat old-generated.txt

Adjust the directory list to your docsDir and locale directories. After review, delete only the listed files:

while IFS= read -r file; do rm -- "$file"; done < old-generated.txt

Anything still left in those directories was not marked generated: true; review it by hand before you remove or move it.

Revision History

ClaudeCreated: 2026-11-20T11:51:25ZUpdated: 2026-11-20T11:51:25Z

AI Assistant

Ask a question about the documentation.

Preview theme

Loading theme previews…