CLI Commands

MokaDocs provides a command-line interface for scaffolding, building, serving, and managing your documentation site. All commands are invoked via the mokadocs executable.

Global Usage

mokadocs <command> [options]

Run mokadocs --help to see all available commands, or mokadocs <command> --help for details on a specific command.

mokadocs init

Scaffolds a new MokaDocs project in the current directory. This creates a starter configuration file and docs folder so you can begin writing documentation immediately.

What It Creates

• mokadocs.yaml — Default site configuration file with common settings pre-filled
• docs/ — Documentation source directory
• docs/index.md — A starter homepage with example front matter and content

Options

This command has no required or optional parameters. It operates on the current working directory.

Usage

# Initialize a new MokaDocs project
mokadocs init

# Typical workflow: create a project directory, then initialize
mkdir my-library-docs
cd my-library-docs
mokadocs init

Behavior

• If mokadocs.yaml already exists in the current directory, the command will warn you and exit without overwriting.
• The generated docs/index.md includes sample front matter demonstrating title, order, and icon properties.

mokadocs build

Builds the documentation site by running the full build pipeline. This processes all Markdown files, analyzes C# projects (if configured), generates API reference pages, builds the search index, and writes the final static site to the output directory.

Options

Exit Codes

Build Output Summary

On a successful build, MokaDocs prints a summary to the console:

Build completed successfully.
  Pages:              24
  API types:          18
  Search entries:     142
  Output:             _site/
  Duration:           1.23s

Usage Examples

# Basic build with default settings
mokadocs build

# Build with a custom config file
mokadocs build --config ./config/mokadocs.prod.yaml

# Build to a custom output directory
mokadocs build --output ./dist

# Build including draft pages (useful during authoring)
mokadocs build --draft

# Watch mode: rebuilds automatically when files change
mokadocs build --watch

# Full clean rebuild with debug logging
mokadocs build --no-cache --verbose

# Build for GitHub Pages subdirectory deployment
mokadocs build --base-path /my-repo

# Combine options
mokadocs build --config mokadocs.yaml --output ./dist --draft --verbose

Notes

• The --watch flag keeps the process running and monitors the docs/ directory and mokadocs.yaml for changes. Press Ctrl+C to stop.
• Using --no-cache is recommended after upgrading MokaDocs or changing theme settings to ensure a clean build.
• The --draft flag is useful during development. Draft pages are excluded from production builds by default.

mokadocs serve

Starts a local development server with hot reload support. This is the recommended way to preview your documentation while writing.

Options

Features

• Hot Reload via WebSocket: The dev server injects a small WebSocket client into served pages. When a source file changes, the browser automatically refreshes without manual intervention.
• File Watching: Monitors the docs/ directory and mokadocs.yaml for changes. Any modification triggers an incremental rebuild followed by a browser refresh.
• Clean URL Support: Serves clean URLs automatically. A request to /guide resolves to /guide/index.html, so your local preview matches production behavior.
• Custom 404 Page: Displays a styled 404 page (with dark/light theme support) when a route is not found.
• REPL Execution Endpoint: When the REPL plugin is active, exposes POST /api/repl/execute for running C# code snippets interactively.
• Blazor Preview Endpoint: When the Blazor plugin is active, exposes POST /api/blazor/preview for rendering Blazor component previews.

Auto-Open Browser

By default, mokadocs serve opens your site in the default browser when the server starts. This works cross-platform (macOS, Windows, and Linux). Use --no-open to disable this behavior.

Usage Examples

# Start the dev server on the default port (5080)
mokadocs serve

# Start on a custom port
mokadocs serve --port 3000

# Start without opening the browser
mokadocs serve --no-open

# Start with a specific config file
mokadocs serve --config mokadocs.prod.yaml

# Start with verbose logging to debug issues
mokadocs serve --verbose

Output

MokaDocs dev server started.
  Listening on:  http://localhost:5080
  Watching:      docs/, mokadocs.yaml
  Hot reload:    enabled (WebSocket)

Press Ctrl+C to stop.

mokadocs new

Scaffolds new pages, plugins, or component examples for your MokaDocs project. This command has three subcommands: page, plugin, and component.

mokadocs new page

Creates a new Markdown documentation page with pre-filled front matter.

Options

Usage

# Create a basic page in the docs directory
mokadocs new page getting-started

# Create a page with a custom title and order
mokadocs new page installation --title "Installation Guide" --order 1

# Create a page in a subdirectory with a specific layout
mokadocs new page overview --path ./docs/guides --layout wide

mokadocs new plugin

Scaffolds a new plugin project with a .csproj file and a starter IMokaPlugin implementation stub. This gives you a working project structure that you can build on immediately.

Usage

# Scaffold a new plugin project
mokadocs new plugin MyCustomPlugin

This creates a directory named MyCustomPlugin containing a .csproj configured for MokaDocs plugin development and a C# file with an IMokaPlugin stub ready to implement.

mokadocs new component

Generates an example page demonstrating a built-in MokaDocs component. Use this to quickly see how a component works and to get starter markup you can copy into your own pages.

Available Components

Usage

# Generate a card component example page
mokadocs new component card

# Generate a code-group example
mokadocs new component code-group

mokadocs doctor

Runs a suite of diagnostic checks against your MokaDocs project and reports any problems found. This is useful for catching configuration issues, broken links, missing metadata, and other common problems before they reach production.

Checks

The doctor command runs 11 built-in checks:

Options

Exit Codes

Usage

# Run all diagnostics
mokadocs doctor

# Run diagnostics with automatic fixes
mokadocs doctor --fix

# Run with a custom config and verbose output
mokadocs doctor --config mokadocs.prod.yaml --verbose

Output is colored using Spectre.Console, with green for passed checks, yellow for warnings, and red for errors.

mokadocs stats

Displays statistics about your documentation project, including page counts, word counts, API coverage, and more.

Output

The command prints a formatted table with the following information:

Options

Usage

# Show project statistics
mokadocs stats

# Output as JSON for CI integration
mokadocs stats --json

# Use a specific config file
mokadocs stats --config mokadocs.prod.yaml

mokadocs clean

Deletes the output directory to remove all previously built files. This is useful before a fresh build or when switching between configurations.

Behavior

• Reads the build.output path from your configuration file (defaults to _site).
• Recursively deletes the entire output directory and its contents.
• If the output directory does not exist, the command exits silently without error.

Usage Examples

# Clean the output directory
mokadocs clean

# Clean and then rebuild
mokadocs clean && mokadocs build

# Clean with a custom config (uses that config's output path)
mokadocs clean --config mokadocs.prod.yaml

mokadocs info

Displays environment and configuration information. This is helpful for debugging issues or when filing bug reports.

Output

MokaDocs Environment Info
  MokaDocs version:  1.2.0
  .NET version:      8.0.100
  OS:                macOS 15.2 (Darwin 24.2.0)
  Config path:       /Users/dev/project/mokadocs.yaml
  Output path:       /Users/dev/project/_site
  Docs path:         /Users/dev/project/docs

Usage

mokadocs info

mokadocs validate (Superseded)

The mokadocs validate command was originally planned but has been superseded by mokadocs doctor, which provides a broader set of diagnostic checks along with auto-fix support. Use mokadocs doctor instead.

Command Cheat Sheet