Installation

How to install and set up zudo-doc for local development.

Prerequisites

• Node.js 22+ — required by zfb and the toolchain

• pnpm — recommended package manager

Create a New Project

The fastest way to get started is with the create-zudo-doc CLI. It scaffolds a new project with an interactive setup wizard.

pnpm create zudo-doc

Or with other package managers:

npm create zudo-doc
yarn create zudo-doc
bunx create-zudo-doc

For non-interactive usage (CI, automation, AI agents), use --yes to accept defaults or pass flags directly:

pnpm create zudo-doc my-docs --yes
pnpm create zudo-doc my-docs --lang ja --scheme Dracula --no-i18n --pm pnpm --install

See the CLI reference for all available flags.

The CLI walks you through the following options:

Project Name

Enter a name for your project directory (default: my-docs).

Default Language

Choose the default language for your documentation site. Supported languages include English, Japanese, Chinese (Simplified/Traditional), Korean, Spanish, French, German, and Portuguese.

Color Scheme Mode

Choose how your site handles color schemes:

• Light & Dark (toggle) — users can switch between light and dark themes. Pick from pre-configured pairings (GitHub, Catppuccin, Solarized, Rosé Pine, Atom One, Everforest, Gruvbox, Ayu) or choose light and dark schemes individually.

• Single scheme — one fixed color scheme for the entire site. 40 schemes are available, including Dracula, Nord, TokyoNight, and more.

When using light/dark mode, you can also set the default mode (light or dark) and whether to respect the user's system color scheme preference.

Features

Select which optional features to include:

Package Manager

Choose your preferred package manager: pnpm (recommended), npm, yarn, or bun. After scaffolding, the CLI will ask whether to install dependencies for you.

Alternative: Clone the Repository

You can also start by cloning the full repository directly:

git clone https://github.com/zudolab/zudo-doc.git my-docs
cd my-docs
pnpm install

Development

pnpm dev

The zfb dev server starts on port 4321 with instant hot module replacement.

Build

pnpm build

This generates static HTML in the dist/ directory. You can deploy it to any static hosting service.

Type Checking

pnpm check

Runs the project's TypeScript type checker in strict mode.

Project Structure

After installation, your project looks like this:

src/
├── components/          # Preact components (server-rendered + client islands)
│   └── admonitions/     # Note, Tip, Info, Warning, Danger
├── config/
│   ├── settings.ts      # Site name, active color scheme
│   ├── color-schemes.ts # All available color presets
│   └── color-scheme-utils.ts
├── content/
│   ├── docs/            # English MDX content
│   └── docs-ja/         # Japanese MDX content
└── styles/
    └── global.css       # Design tokens & Tailwind config

pages/                   # zfb file-based routing (.tsx page modules)
zfb.config.ts            # zfb engine entry-point config

See the Writing Docs guide for how to create and organize your documentation pages.