Development Workflow
Development commands, build tools, and component development patterns for zudo-doc.
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 |
Tip
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 |
Tip
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: 23-step pipeline (format check → ... → Worker contract proof → build → link check → HTML validation → preview smoke); scripts/ 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) |
Note
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/ — 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 is a Preact-only project running on zfb. All components are .tsx files. The distinction is whether a component runs only on the server, or also hydrates on the client.
Server-rendered Preact 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, theme toggle, 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. 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/ supplies the shared .zd-content stylesheet, while package Preact 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:
Create a
.mdxfile undersrc/withcontent/ docs/ titleandsidebar_positionin the frontmatter.Write content starting with
## h2headings. Do not add# h1— the frontmattertitlerenders as the page h1.Create a matching file under
src/with translated prose.content/ docs- ja/ Keep all code blocks identical between EN and JA — only translate the surrounding prose.
Run
pnpm formatto format MDX files.Run
pnpm buildto verify the site builds correctly.
Tip
Always set sidebar_position in frontmatter. Without it, pages sort alphabetically, which is rarely the intended order.
See the Frontmatter reference for all available frontmatter fields.