CLI Commands

DocAnvil provides six subcommands: new, theme, doctor, serve, build, and export.

Global Flags

docanvil new

Scaffold a new documentation project.

docanvil new <name>

Creates a project directory with:

• docanvil.toml — project configuration
• nav.toml — navigation structure
• docs/ — content directory with starter pages
• theme/custom.css — empty custom stylesheet

# Create a docs project
docanvil new my-docs

# Create and immediately start serving
docanvil new my-docs && cd my-docs && docanvil serve

docanvil theme

Interactively generate a custom color theme for your project.

docanvil theme [--overwrite] [--path <dir>]

The command walks through an interactive prompt:

1. Color mode — choose Light only, Dark only, or Both (light + dark with toggle)
2. Primary color — hex code for the primary accent color (prompted once per mode)
3. Secondary color — hex code for the warning/secondary color (prompted once per mode)

It then derives all color-related CSS variables, writes them to theme/custom.css, and updates docanvil.toml with both custom_css and color_mode.

If existing theme customizations are detected (custom_css or [theme.variables] in config), the command exits with a helpful message unless --overwrite is passed.

# Generate a theme for the current project
docanvil theme

# Generate a theme for a project in another directory
docanvil theme --path ../my-docs

# Replace an existing theme
docanvil theme --overwrite

Color Modes

When "Both" is selected, you are prompted for separate primary and secondary colors for each mode, allowing independent light and dark palettes.

Derived Variables (Light)

From the two input colors, the following CSS variables are generated for light mode:

Derived Variables (Dark)

Dark mode uses inverted derivation logic plus explicit background and text colors:

docanvil doctor

Diagnose project configuration and content issues before building.

docanvil doctor [--fix] [--strict] [--format <fmt>] [--path <dir>]

# Check the current project
docanvil doctor

# Check and auto-fix safe issues
docanvil doctor --fix

# Use in CI to fail on any issues
docanvil doctor --strict

# Check a project in another directory
docanvil doctor --path ../my-docs

If no docanvil.toml is found, doctor prints a friendly message suggesting docanvil new and exits cleanly.

Machine-readable output

The --format flag switches from the default coloured terminal output to structured XML, which is useful for integrating with CI annotation tools or test reporters. Machine-readable output is written to stdout; progress messages are suppressed entirely.

# Output Checkstyle XML (e.g. pipe to reviewdog)
docanvil doctor --format checkstyle

# Output JUnit XML (e.g. for GitHub Actions test summary)
docanvil doctor --format junit

# Fail CI and emit Checkstyle XML
docanvil doctor --format checkstyle --strict

# Save JUnit results to a file
docanvil doctor --format junit > test-results/doctor.xml

Checkstyle XML groups diagnostics by file. Each <error> element carries:

• severity — info, warning, or error
• message — the diagnostic message
• line — source line number (0 when not applicable)
• source — docanvil.{category}.{check} (e.g. docanvil.readability.long-paragraph)

JUnit XML maps each check category to a <testsuite>. All eight categories are always emitted — categories with no issues produce a single passing <testcase name="all-checks-passed"/>. Warnings and errors appear as <failure> elements; info diagnostics appear as <skipped/>.

Check categories

The doctor runs six categories of checks, expanding to eight when versioning and/or i18n is enabled:

1. Project structure — config file, content directory, index page
2. Configuration — TOML parsing, file references (logo, favicon), nav.toml validation
3. Theme — custom CSS file existence, layout template Tera syntax
4. Content — broken wiki-links, unclosed directives, front-matter JSON errors, duplicate slugs
5. Readability — content quality checks across all Markdown source files (see below)
6. Versions (versioning only) — version configuration and directory health
7. Translations (i18n only) — translation coverage across enabled locales
8. Output — output directory writability

Readability checks

These run against raw Markdown source and catch content quality issues before they reach readers. Each diagnostic includes the file path and line number.

Heading structure

Links and images

Code blocks

Prose quality

All checks skip content inside fenced code blocks. Most also strip inline code spans before scanning to avoid false positives.

Version checks

These run when version.enabled is non-empty in docanvil.toml.

Auto-fix

The --fix flag applies safe, non-destructive fixes:

Readability issues are never auto-fixed — they require human judgment.

docanvil serve

Start a development server with live reload.

docanvil serve [--host <address>] [--port <port>] [--path <dir>]

The server:

• Builds the site on startup
• Watches all project files for changes (Markdown, TOML, CSS, templates)
• Rebuilds affected pages on file change
• Notifies the browser via WebSocket at /__docanvil_ws
• The browser reloads automatically — no manual refresh needed

# Default: localhost:3000
docanvil serve

# Custom host and port
docanvil serve --host 0.0.0.0 --port 8080

# Verbose output to see rebuild events
docanvil serve --verbose

# Serve a project from another directory
docanvil serve --path ../my-docs

docanvil build

Generate the static HTML site for deployment.

docanvil build [--out <path>] [--clean] [--path <dir>]

The build pipeline processes each page through:

1. Directive expansion (components)
2. Popover conversion
3. Markdown rendering (comrak with GFM)
4. Wiki-link resolution
5. Inline attribute injection
6. Template wrapping (Tera layout)

Static assets (custom CSS, images) are copied to the output directory.

# Default build to dist/
docanvil build

# Clean build to a custom directory
docanvil build --out public --clean

# Build a project from another directory
docanvil build --path ../my-docs

docanvil export

Export your documentation to other formats.

docanvil export pdf

Export docs as a single PDF using Chrome or Chromium.

docanvil export pdf --out <path> [--path <dir>] [--locale <code>]

Requires Chrome or Chromium. DocAnvil searches common install locations on macOS, Windows, and Linux before falling back to PATH.

# Export the current project
docanvil export pdf --out guide.pdf

# Export a single locale
docanvil export pdf --out guide-fr.pdf --locale fr

# Export all enabled locales (i18n projects)
docanvil export pdf --out guide.pdf --locale all

# Export a project in another directory
docanvil export pdf --out guide.pdf --path ../my-docs

PDF output is configured via the [pdf] section in docanvil.toml. See PDF Export for the full guide, including cover pages, paper sizes, RTL support, and custom CSS.

Exit Codes

All commands return structured exit codes so CI pipelines can distinguish between different failure types:

You can use these in CI scripts to handle different failures appropriately:

docanvil build --strict
code=$?
case $code in
  0) echo "Build succeeded" ;;
  2) echo "Fix your docanvil.toml" ;;
  3) echo "Content issues found — check warnings above" ;;
  *) echo "Build failed with exit code $code" ;;
esac

Related Pages

• Installation — install and create your first project
• Configuration — docanvil.toml and nav.toml reference
• PDF Export — cover pages, paper sizes, RTL support, and per-locale export