## Commands in a Fresh Scaffold

A project created with `create-zudo-doc` starts with these scripts:

| Command | What it does |
|---|---|
| `pnpm dev` | Start the zfb development server |
| `pnpm build` | Export static HTML to `dist/` |
| `pnpm preview` | Serve the built `dist/` output locally |
| `pnpm check` | Run TypeScript type checking |

[Dynamic content unavailable in text export]

Feature choices can add scripts to the generated `package.json`; treat that file as the project's command reference.



## Contributing to This Repository

This repository is also zudo-doc's showcase. Its commands include package development, doc-history data, and CI tooling that a fresh scaffold does not ship.

### Development Commands

| Command | What it does |
|---|---|
| `pnpm dev` | Runs the zfb dev server (port 4321), doc-history-server (port 4322), package watch, and showcase development helpers concurrently |
| `pnpm dev:zfb` | zfb dev server only (port 4321) |
| `pnpm dev:history` | doc-history API server only (port 4322) |
| `pnpm dev:zudo-doc` | Watches the `@takazudo/zudo-doc` package — tsup `--watch` for the JS and `tsc --watch` for the type declarations, in parallel |
| `pnpm dev:stable` | Alternative build-then-serve mode (avoids HMR crashes on content file add/remove) |
| `pnpm dev:network` | zfb dev server with `--host 0.0.0.0` for LAN access |

[Dynamic content unavailable in text export]

Use `pnpm dev:stable` when you're adding or removing showcase content files frequently. Standard `pnpm dev` can crash on file system changes due to Vite HMR.



### Build & Quality Commands

| Command | What it does |
|---|---|
| `pnpm build` | Static HTML export to `dist/` |
| `pnpm check` | TypeScript type checking |
| `pnpm b4push` | Pre-push validation: validation pipeline (format check → ... → Worker contract proof → build → link check → HTML validation → preview smoke); `scripts/run-b4push.sh` is authoritative for the current count. E2E runs in CI (pr-checks), not in b4push, for time-budget reasons |
| `pnpm format` | Format MDX files |
| `pnpm test:unit` | Run unit tests (Vitest) |
| `pnpm test:e2e` | Run E2E tests (Playwright) |

[Dynamic content unavailable in text export]

Run `pnpm b4push` before pushing to verify the full site builds and all links resolve. It runs a bounded pipeline (format check through preview smoke); E2E tests run in CI (pr-checks), not in this pipeline, for time-budget reasons.

The canonical, authoritative b4push step list lives in the header comment of `scripts/run-b4push.sh` — treat that script as the single source of truth, and consult it rather than any inline summary if the steps appear to disagree.



## Component Development

zudo-doc uses zfb’s zudo-react runtime. All components are `.tsx` files. The distinction is **whether a component runs only on the server, or also hydrates on the client**.



### Server-rendered zudo-react components

By default, every `.tsx` component renders to HTML at build time and ships zero client-side JavaScript. This is the right choice for:

- Layout wrappers
- Static UI elements (headers, footers, sidebars without interactivity)
- Anything that doesn't require runtime state or DOM events

### Client-hydrated islands

When a component needs interactivity — local state, event handlers, animations — wrap it with zfb's `Island()` helper at its render site. Server-rendered output is reused; only the interactive part hydrates.

The standard chrome islands — including the table of contents, mobile TOC, sidebar tree and toggles, appearance menu, and doc history — are implemented by `@takazudo/zudo-doc`. A fresh scaffold consumes those package components; it does not contain copies of their source files.

This showcase retains a couple of project-specific integrations: `client-router-bootstrap` and the `preset-generator` island. The Design Token Panel bootstrap is package-owned and reaches the island scanner through the static package route → chrome → derive import chain. These are showcase implementation details, not a starter inventory for new projects.

To add a project-owned presentational component or an interactive island to a scaffold, follow the [Custom Components guide](https://zudo-doc.takazudomodular.com/docs/guides/custom-components). It covers the `mdxExtras` registration path and the static import route required for an island to be discovered.

Use client-hydrated islands for:

- Scroll spy (TOC highlighting)
- Toggle/drawer components
- Live editing panels

### Content Typography Components

Content typography is package-owned. `@takazudo/zudo-doc/content.css` supplies the shared `.zd-content` stylesheet, while package zudo-react components render the major MDX HTML overrides on the server with no client hydration.

The default component map covers headings (h2–h4), paragraph, link, strong, blockquote, lists (ul/ol), and tables. A project can override those bindings, or add other MDX components, through `mdxExtras`.

Use `mdxExtras` when a project needs intentional MDX rendering changes; keep shared typography fixes in the package rather than copying `.zd-content` rules into a project's `global.css`.

## Content Development Cycle

Follow these steps when adding new documentation pages:

1. Create a `.mdx` file under `src/content/docs/` with `title` and `sidebar_position` in the frontmatter.
2. Write content starting with `## h2` headings. Do not add `# h1` — the frontmatter `title` renders as the page h1.
3. Create a matching file under every configured additional-locale directory (for example, `src/content/docs-ja/` and `src/content/docs-de/`) with translated prose.
4. Keep all code blocks identical across the primary and configured locale trees — only translate the surrounding prose.
5. Run `pnpm format` to format MDX files.
6. Run `pnpm build` to verify the site builds correctly.

[Dynamic content unavailable in text export]

Always set `sidebar_position` in frontmatter. Without it, pages sort alphabetically, which is rarely the intended order.



See the [Frontmatter reference](https://zudo-doc.takazudomodular.com/docs/guides/frontmatter) for all available frontmatter fields.