Documentation Site

How the zudo-doc documentation site is authored, checked, built, and deployed.

`doc/` and `docs/`

This site is the repository's English developer documentation. It is separate from the root docs/ directory, which remains the operator-reference surface for creator bootstrap, SiteProject releases, packed installs, browser acceptance, demo sites, and hosted deployment. Use the operator references from their canonical GitHub URLs: SiteProject, packed host install, workspace acceptance, and hosted demo.

Site layout

The doc/ workspace owns the configuration, content, route seams, static assets, and package CSS integration:

doc/
├── zfb.config.ts                 # zudo-doc config, Drift theme, header nav
├── src/content/docs/             # filesystem-backed navigation and MDX
│   ├── overview/<page>.mdx
│   ├── architecture/<page>.mdx
│   ├── setup/<page>.mdx
│   └── development/<page>.mdx
├── pages/index.tsx               # package home route
├── pages/docs/[[...slug]].tsx    # host-owned docs route seam
├── src/styles/global.css         # package CSS/Tailwind layer setup
└── public/                       # static site assets and favicon files

The top-level content directories are the four header categories. A category index.mdx is its landing page, and each sibling page is a sidebar item. The header's categoryMatch values in zfb.config.ts match those directory names; there is no separate sidebar registry to update.

Author, check, and build

Run the root wrappers from the repository root:

Command	Purpose
`corepack pnpm doc:dev`	Starts the zfb site and document-history server for local authoring.
`corepack pnpm doc:build`	Builds the static zudo-doc site into `doc/dist/`.
`corepack pnpm doc:check`	Runs zfb content and TypeScript checks.
`corepack pnpm doc:build-site`	Builds the static site, writes `doc-site-manifest.json`, and verifies the `doc/dist` deployment artifact.

The package-local equivalents are pnpm -C doc dev, pnpm -C doc build, and pnpm -C doc check. The root doc:build-site wrapper runs the package build, then writes and verifies the deployment manifest while preserving the root-mounted doc/dist/ shape. Use doc:build when you need only the raw static site without its deployment manifest.

Build output is ignored. A clean build must not leave tracked or unexpected doc/dist/, doc/.zfb/, or doc/.zfb-build/ files. Because the site's base is /, emitted links and asset URLs are root-relative; the output contains index.html, 404.html, docs/<category>/<page>/index.html, and assets/.

Writing rules

Before creating or editing an MDX page, invoke /zudo-doc-writing. Plan or re-read the complete navigation tree first, then place the page in the matching filesystem category. Follow these rules:

Every page has frontmatter title and sidebar_position; content pages also have a one-sentence description.
Every category has an index.mdx with a short introduction and <CategoryNav category="<category>" />; keep full content in sibling pages.
The frontmatter title supplies the h1. Start the body at ##; do not add a body h1 or a body --- separator.
Link between site pages with relative paths including the .mdx extension, such as [Validation gates](./validation-gates.mdx). Use ordinary URLs for external references, including the GitHub operator links above.
Use the supported admonitions without imports. Leave a blank line after an opening ::: and before its closing fence.
Keep directory and filename segments in kebab-case. The filesystem is the navigation, so adding a directory or page changes the sidebar.

Theme, dependencies, and deployment

doc/zfb.config.ts selects the Drift theme pack and the site URL https://zc-doc.zudolab.dev. ZUDO_DEPS_PINS.md records the generated create-zudo-doc@5.22.1 scaffold, @takazudo/zudo-doc and history server 5.22.1, and the pinned zfb/runtime/MD renderer dependencies at 2.16.0. Keep those provenance notes with the scaffold/config changes; do not silently upgrade the theme or runtime while editing prose.

The hosted pipeline's documentation job is doc-site-build. It runs doc:build-site, verifies doc/dist, and uploads the CI artifact doc-site-<sha>. The trusted-run target is doc on Worker zudo-composer-doc using wrangler.doc.jsonc at zc-doc.zudolab.dev; its artifact manifest is doc-site-manifest.json.

The target's verifyArtifact hook uses verifyDocSiteArtifact, while liveRoutes reads that manifest's routes. Its routeFile and assetUrl hooks map each route to its own HTML and fetch canonical asset URLs, matching Wrangler's default auto-trailing-slash handling and explicit 404-page fallback. The pipeline's live delivery contract describes those mappings. Local builds may omit sourceRevision; CI records the full source SHA, and production preflight requires it to match the trusted run before any Wrangler call.