create-zudo-doc CLI

Complete CLI reference for the create-zudo-doc project scaffolder.

Usage

create-zudo-doc [project-name] [options]

When run without flags, the CLI launches an interactive wizard. All options can be specified via flags for non-interactive (CI/agent) usage.

You can also use the Setup Preset Generator to interactively build a configuration and copy it as a JSON preset or CLI command.

What the CLI generates

The scaffold is minimal — roughly a dozen files (see Project Structure). The layout, chrome, and schema all ship from @takazudo/zudo-doc and are consumed from node_modules, so the generated project holds only what is genuinely its own.

Your feature choices are written into a single zfb.config.ts as a zudoDoc({ … }) call containing only the fields that differ from the defaults (siteName is always emitted). There is no separate src/config/settings.ts — the one config file is the whole configuration surface. See Configuration for every field.

A few things a fresh scaffold intentionally does not include:

• No .zudo-doc.json — the eject provenance file is lazy-created on your first zudo-doc eject, so an un-ejected project never carries it.

• No check:html / HTML-validation step and no gen:z-index / check:z-index codegen — both were pruned from generated projects. The default z-index tiers ship from the package; HTML validation and pre-push suites are opt-in add-backs (see Customizing → Restoring pre-push and HTML validation).

• No deploy adapter or wrangler.toml — the default build is a pure static export. Deploying (or enabling SSR features like the AI assistant) is an explicit extend step.

Color Schemes

zudo-doc ships exactly two color schemes — Default Light and Default Dark — sharing one set of OKLCH ramps. There is no bundled catalog of community or terminal presets to pick a --scheme value from.

Customization happens one level deeper, through the colorSchemes escape-hatch field in zfb.config.ts: pass your own { ramps, map } palette map to zudoDoc({ colorSchemes: { … } }) (see Color — "Adding a Custom Color Scheme"). Preview the result live in the Design Token Panel's Palette tab (see Color Scheme Preview) before committing it to source.

Theme Packs

Independently of the color scheme, the scaffold can start a project on any bundled theme pack — a prebuilt design bundle layered on top of the scheme system. Pass --theme-pack <slug>, or answer the interactive "Theme pack:" prompt (asked between the color-scheme questions and the feature multiselect). The chosen slug is written to themePack in the generated zfb.config.ts (only when it differs from default, per the diff-from-defaults rule). The on-page switcher UI is a separate feature toggle, --theme-pack-switcher.

Options

Project

Color Scheme

Theme Pack

Features

Preset

The --preset flag accepts the JSON output from the Setup Preset Generator. When a preset is loaded, all prompts are skipped (same as --yes). Individual CLI flags override preset values.

General

Supported Languages

The --lang flag accepts any of the following language codes:

The default language determines the locale used for root pages (/docs/...). When i18n is enabled, a secondary language is added automatically (English when the default is non-English, Japanese when the default is English).

Examples

Interactive mode

pnpm create zudo-doc

Non-interactive with all defaults

pnpm create zudo-doc my-docs --yes

Japanese site, single dark scheme

pnpm create zudo-doc my-docs --lang ja --scheme "Default Dark" --no-i18n --pm pnpm --install

Light/dark mode with an explicit default mode

pnpm create zudo-doc my-docs \
  --color-scheme-mode light-dark \
  --default-mode light \
  --no-respect-system-preference \
  --yes

Using a preset file

Generate a preset JSON from the Setup Preset Generator, save it to a file, then pass it to the CLI:

pnpm create zudo-doc --preset setup.json --install

Or pipe JSON directly via stdin:

cat setup.json | pnpm create zudo-doc --preset - --install

CI/automation usage

pnpm create zudo-doc my-docs \
  --lang en \
  --scheme "Default Dark" \
  --no-i18n \
  --search \
  --no-claude-resources \
  --pm pnpm \
  --install \
  --yes

Programmatic API

The package also exports a programmatic API. The options object accepts the same fields as the JSON preset, plus install and git options. The programmatic API defaults both to false.

import { createZudoDoc } from "create-zudo-doc";

await createZudoDoc({
  projectName: "my-docs",
  defaultLang: "en",
  colorSchemeMode: "light-dark",
  lightScheme: "Default Light",
  darkScheme: "Default Dark",
  defaultMode: "dark",
  respectPrefersColorScheme: true,
  themePack: "foundry",
  features: [
    "search",
    "sidebarFilter",
    "sidebarResizer",
    "sidebarToggle",
    "tocToggle",
    "docHistory",
    "footerCopyright",
  ],
  cjkFriendly: false,
  minifyHtml: true,
  headerRightItems: [
    { type: "component", component: "theme-toggle" },
    { type: "component", component: "github-link" },
  ],
  metaTags: {
    description: true,
    ogImage: "/img/ogp.png",
  },
  packageManager: "pnpm",
  install: true,
  git: true,
});

headerRightItems (see the Header Right Items guide) and metaTags (see Configuration) accept the same shapes as the JSON preset fields of the same name, and are validated with the same rules — an unknown headerRightItems component/trigger name or an invalid metaTags sub-field type throws before scaffolding starts.