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:

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

Build & Quality Commands

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. 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.

See the Frontmatter reference for all available frontmatter fields.