Document Sources
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 /.
The setting is optional and defaults to []. With no entries nothing is generated, and any output left by an earlier configuration is removed.
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 / and /.
The package plugin (@takazudo/) does all filesystem work at build time; zudoDoc() wires it in automatically. The setting itself is plain data.
Preset Entries
| Field | Type | Description |
|---|---|---|
id | string | Stable source identifier (letters, digits, -, _). Also the default mount |
preset | "claude-code" | "codex" | The bundled preset to expand |
root | string | The agent configuration directory, such as .claude or .codex. It must exist |
scanRoot | string | Optional directory scanned for instruction files (and, for Codex, .agents/skills). Defaults to the project root |
mount | string | Optional 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
| Section | Route | Source |
|---|---|---|
| Instructions | / | Every CLAUDE.md below scanRoot |
| Commands | / | <root>/commands/**/*.md |
| Skills | / | <root>/ and the files beside it |
| Agents | / | <root>/agents/**/*.md |
The root CLAUDE.md is the Instructions landing page. A nested packages/ becomes / and is titled by its path.
Codex preset
| Section | Route | Source |
|---|---|---|
| Instructions | / | Every AGENTS.md and AGENTS.override.md below scanRoot |
| Config | / | config.toml, config.toml.example, and *.config.toml profiles in root |
| Agents | / | <root>/agents/*.toml |
| Hooks | / | <root>/ and every file below <root>/hooks/ |
| Rules | / | <root>/rules/*.rules |
| Skills | / | <root>/ and <scanRoot>/ |
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 /. It lists the skill's file structure, and other Markdown files in the skill directory (for example references/) 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:
| Field | Type | Description |
|---|---|---|
id | string | Stable source identifier. Also the default mount |
title | string | Title of the source's landing page |
mount | string | Optional top-level route segment. Defaults to id |
mappings | array | One or more mappings (below) |
Each mapping selects files from one root:
| Field | Type | Description |
|---|---|---|
id | string | Mapping identifier, unique within the source |
root | string | Directory to read from |
include | string[] | Glob patterns relative to root |
exclude | string[] | Optional glob patterns removed from include |
to | string | Optional 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:
markdownrenders Markdown with its frontmatter.title(orname), the first#heading, or the file name becomes the page title;descriptionis kept; other scalar frontmatter fields are shown as a table.codeshows the whole file in a highlighted code block titled by its file name. A leading comment line becomes the description.skilltreats each selectedSKILL.mdas a skill package, as the presets do.
Example: a sibling handbook and personal notes
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 . and ., and ~/, 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.mdExample: 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.jsonTwo mappings publish the Markdown as pages and the JSON as source code:
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 /, / and /, plus synthesized indexes for /, /, / and /. A link from GROK.md to prompts/ is rewritten to the generated page.
Routes and Landing Pages
Every page lives at /, 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
markdownorskillmapping,index.md,index.mdxandREADME.mdbecome 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
toor a source'smount.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:
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 and Assets
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.mddoc_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 .. 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:
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.
Symlinks and Excluded Directories
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 watchzudo-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.
// 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 route | New route |
|---|---|
/ | / |
/ | / |
/ | / |
/ | / |
/ | / |
/ | / |
/ | / |
/ | / |
/ | / |
/ | / |
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.txtAdjust 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.txtAnything still left in those directories was not marked generated: true; review it by hand before you remove or move it.