Command Line Interface (CLI)

The Boltdocs CLI provides a suite of developer commands to build, preview, debug, and maintain documentation projects.

Quick Start

Execute commands using npx boltdocs or by defining scripts inside your package.json:

# Start the local development server
npx boltdocs dev

# Build the static site for production
npx boltdocs build

# Run project integrity and health diagnostics
npx boltdocs doctor

# Audit plugin dependencies for security warnings
npx boltdocs audit

# Generate MDX changelog logs from CHANGELOG.md
npx boltdocs generate-changelog CHANGELOG.md

Core Workflow Commands

`dev`

Starts a high-performance local development server powered by Vite. Features instant Hot Module Replacement (HMR) for MDX files, stylesheet edits, and configuration hot-reloads.

Usage: boltdocs dev [root] [options] (or simply boltdocs [root] [options])
Default Directory: process.cwd()

Options

Option	Description
`--port <number>`	The port number the development server should listen on (defaults to `5173`).
`--host [address]`	The host IP address the server should bind to (e.g. `0.0.0.0` or `true` to expose to the local network).
`--force`	Force Vite to optimize and pre-bundle dependencies again, ignoring cache (maps to `optimizeDeps.force: true`).

`build`

Compiles documentation pages into highly optimized, fully static HTML and JavaScript assets via the React Static Site Generation (SSG) engine.

Usage: boltdocs build [root]

`preview`

Serves the generated static production bundle from the local dist/ directory, allowing you to test performance, redirects, SEO tags, and page rendering before deploying.

Usage: boltdocs preview [root] [options]

Options

Option	Description
`--port <number>`	The port number the preview server should listen on (defaults to `4173`).
`--host [address]`	The host IP address the preview server should bind to.

Performs a fast static analysis of the source code of all active plugins. It scans for potentially sensitive behaviors like network calls or environment variable access, giving you total visibility before compiling final assets.

Usage: boltdocs audit [root]

`doctor` (Diagnostics & Integrity Check)

The doctor command runs a set of automated diagnostic checks across your documentation directory to identify broken links, malformed frontmatter, missing translations, and other structural issues.

# Run doctor in the current folder
npx boltdocs doctor

# Run with automated fixing enabled
npx boltdocs doctor --fix

# Verify external URLs in addition to internal routes
npx boltdocs doctor --check-external

# Initialize default doctor.json config file
npx boltdocs doctor --init

# Check build performance against configured budgets
npx boltdocs doctor --budget

CLI Command Options

Option	Description
`--fix`	Automatically corrects repairable issues like broken relative paths and aligns missing i18n keys.
`--check-external`	Performs asynchronous network verification for external web links. (Slower)
`--init`	Creates a default `doctor.json` configuration file in the project root folder.
`--budget`	Checks build performance metrics against configured budgets. Requires a prior `boltdocs build`.

`doctor.json` Configuration Reference

You can customize the diagnostic checks, target files, severities, and CI/CD parameters by creating a doctor.json file in your root directory.

{
  "$schema": "https://boltdocs.vercel.app/schemas/doctor-config.schema.json",
  "checks": {
    "metadata": {
      "enabled": true,
      "titleMin": 10,
      "titleMax": 60,
      "descriptionMin": 50,
      "required": ["title", "description"],
      "optional": [],
      "validateDates": false
    },
    "links": {
      "internal": true,
      "external": false,
      "timeout": 10000,
      "concurrency": 10,
      "ignore": []
    },
    "i18n": {
      "enabled": true
    },
    "performance": {
      "enabled": true,
      "budgets": {
        "maxJSBundleSize": "200kb",
        "maxCSSBundleSize": "30kb",
        "maxPageHTMLSize": "80kb",
        "maxImagesKB": 500,
        "maxBuildTime": 30000,
        "maxFontCount": 3
      }
    }
  },
  "fix": {
    "confirmChanges": false,
    "backupFiles": false,
    "backupPath": ".boltdocs/backups"
  },
  "reporting": {
    "format": "pretty",
    "outputFile": ".boltdocs/reports/doctor.json",
    "failOnError": false,
    "maxWarnings": -1
  },
  "severity": {
    "missingTranslation": "warning",
    "brokenLink": "high",
    "brokenAnchor": "warning",
    "largeFile": "warning",
    "orphanedPage": "low",
    "duplicateTitle": "low",
    "shortMetadata": "low",
    "missingMetadata": "warning",
    "malformedFrontmatter": "high",
    "invalidFrontmatter": "high",
    "budgetExceeded": "warning"
  },
  "exclude": []
}

Diagnostic Check Properties (`checks`)

Property	Type	Default	Description
`metadata`	`MetadataChecks`	Defaults	SEO title, description length, and required frontmatter.
`links`	`LinkChecks`	Defaults	Internal/external links, timeout, concurrency settings, and ignores.
`i18n`	`I18nChecks`	Defaults	Translation synchronization validity.
`performance`	`PerformanceChecks`	Defaults	Build performance budgets against thresholds.

MetadataChecks

Property	Type	Default	Description
`enabled`	`boolean`	`true`	Turn frontmatter/SEO metadata checking on or off.
`titleMin`	`number`	`10`	Minimum character length for page titles.
`titleMax`	`number`	`60`	Maximum character length for page titles.
`descriptionMin`	`number`	`50`	Minimum character length for page descriptions.
`required`	`string[]`	`["title", "description"]`	Frontmatter keys that must be defined on every page.
`optional`	`string[]`	`[]`	Extra frontmatter fields that are allowed.
`validateDates`	`boolean`	`false`	Validate frontmatter date formats.

LinkChecks

Property	Type	Default	Description
`internal`	`boolean`	`true`	Verify relative document links and slug anchors (`#section`).
`external`	`boolean`	`false`	Asynchronously fetch and test remote links.
`timeout`	`number`	`10000`	Network timeout for external checks in milliseconds.
`concurrency`	`number`	`10`	Max parallel threads for remote link checker.
`ignore`	`string[]`	`[]`	List of regex patterns or exact urls to bypass.

I18nChecks

Property	Type	Default	Description
`enabled`	`boolean`	`true`	Checks for missing keys in localized versions compared to default.

PerformanceChecks

Property	Type	Default	Description
`enabled`	`boolean`	`true`	Run performance budget checks on build output.
`budgets`	`object`	See below	Threshold overrides for each metric.

The budgets object supports these optional thresholds:

Property	Type	Default	Description
`maxJSBundleSize`	`string`	`"200kb"`	Max total JS bundle size (supports `b`, `kb`, `mb` suffixes).
`maxCSSBundleSize`	`string`	`"30kb"`	Max total CSS bundle size.
`maxPageHTMLSize`	`string`	`"80kb"`	Max HTML size for a single page.
`maxImagesKB`	`number`	`500`	Max total image asset size in KB.
`maxBuildTime`	`number`	`30000`	Max build time in milliseconds.
`maxFontCount`	`number`	`3`	Max number of font files.

Automated Fix Behavior (`fix`)

Property	Type	Default	Description
`confirmChanges`	`boolean`	`false`	Prompts you interactively before writing auto-fixes.
`backupFiles`	`boolean`	`false`	Create a copy of the source document before auto-fixing.
`backupPath`	`string`	`".boltdocs/backups"`	Folder where temporary pre-fix files will be saved.

Diagnostic Reporting (`reporting`)

Property	Type	Default	Description
`format`	`'pretty' \| 'json' \| 'silent'`	`'pretty'`	Output style interface. `'pretty'` renders cli boxes, `'json'` outputs raw data.
`outputFile`	`string`	`".boltdocs/reports/doctor.json"`	Path to write the diagnostic report file.
`failOnError`	`boolean`	`false`	Force the process to exit with status `1` if a `high` severity issue is found.
`maxWarnings`	`number`	`-1`	Number of allowed warnings before process fails. `-1` is infinite.

`generate-changelog` (Changelog Generator)

The generate-changelog utility parses a unified CHANGELOG.md file (supporting Keep A Changelog, Standard Version, and Semantic Release structures) and automatically decomposes it into individual version pages formatted for the Boltdocs theme UI.

# Decompose CHANGELOG.md and output pages under docs/changelog
npx boltdocs generate-changelog CHANGELOG.md

CLI Command Options

Option	Default	Description
`-o, --output <path>`	`'docs/changelog'`	Destination output folder where version files are generated.
`-t, --title <text>`	`'Changelog'`	Heading title tag injected inside generated pages.
`-l, --limit <number>`	`undefined`	Restricts the number of generated MDX files to the latest N versions.
`--infer-tab`	`true`	Infers active sidebar tabs configuration grouping from output directories.

Layout Output Structure

Each version is parsed, grouped by update types (Features, Bug Fixes, Performance, Refactor, Documentation, Chore), and generated as individual incremental pages:

docs/changelog/
├── 1.v2.0.0.md
├── 2.v1.1.0.md
└── 3.v1.0.0.md

Inside the generated page, the metadata looks like:

---
title: v2.0.0
badge: "Major"
description: Changelog version 2.0.0 (2026-05-20)
---

# Changelog v2.0.0

**Released:** 2026-05-20

## Feature
- Add high performance rust compiler pipeline.
  - **Author:** @jesusalcaladev
  - **Commit:** `483fa9c`

To link the generated changelog pages into your navbar, register the route inside boltdocs.config.ts:

export default defineConfig({
  theme: {
    navbar: [
      { label: 'Documentation', href: '/docs' },
      { label: 'Changelog', href: '/changelog' } // Automatically matches docs/changelog folder routes
    ]
  }
})

Last updated on July 27, 2026

CLI Reference

Command Line Interface (CLI)

Quick Start

Core Workflow Commands

`dev`

Options

`build`

`preview`

Options

`audit`

`doctor` (Diagnostics & Integrity Check)

CLI Command Options

`doctor.json` Configuration Reference

Diagnostic Check Properties (`checks`)

MetadataChecks

LinkChecks

I18nChecks

PerformanceChecks

Automated Fix Behavior (`fix`)

Diagnostic Reporting (`reporting`)

`generate-changelog` (Changelog Generator)

CLI Command Options

Layout Output Structure

Integrating with Navigation Navbar

Was this page helpful?