md-book

MD-Book Documentation Generator Skill

Use this skill when working with MD-Book, a modern mdbook replacement for generating HTML documentation from Markdown files.

Overview

MD-Book is a Rust-based documentation generator that converts Markdown files to beautiful, searchable HTML documentation. It supports multiple markdown formats (Markdown, GFM, MDX), server-side syntax highlighting, live development server, and integrated Pagefind search.

CLI Usage

Basic Commands

# Build documentation (converts markdown to HTML)
md-book -i input_dir -o output_dir

# Development mode with file watching
md-book -i input_dir -o output_dir --watch

# Development with built-in server (default port 3000)
md-book -i input_dir -o output_dir --serve

# Full development mode (watch + serve on custom port)
md-book -i input_dir -o output_dir --watch --serve --port 8080

CLI Options

Option	Short	Description
--input	-i	Input directory containing markdown files (required)
--output	-o	Output directory for HTML files (required)
--config	-c	Optional path to config file
--watch	-w	Watch for changes and rebuild
--serve	-s	Serve at http://localhost:3000
--port		Port to serve on (default: 3000)

Running from Source

# Clone and build
git clone https://github.com/terraphim/md-book.git
cd md-book
cargo build --release

# Run from source
cargo run -- -i docs -o output
cargo run -- -i docs -o output --serve --watch

Configuration

Configuration Priority (highest to lowest)

1. CLI arguments
2. Environment variables (MDBOOK_ prefix)
3. Custom config file (--config flag)
4. book.toml in current directory
5. Default values

book.toml Configuration

Create book.toml in your input directory:

[book]
title = "My Documentation"
authors = ["Your Name"]
description = "Documentation description"
language = "en"

[output.html]
# Security: raw HTML in markdown is DISABLED by default
allow-html = false  # Set to true only if you trust all content authors
mathjax-support = false

Environment Variables

# Override book title
MDBOOK_BOOK.TITLE="My Book" md-book -i input -o output

# Nested configuration values use underscore
MDBOOK_OUTPUT.HTML.MATHJAX_SUPPORT=true md-book -i input -o output

Project Structure

Input Directory

input/
  index.md          # OPTIONAL: Custom home page content
                    # If present: renders your markdown as home page
                    # If absent: auto-generates card-based navigation
  getting-started.md
  configuration.md
  advanced/         # Subdirectories become sections
    topic1.md
    topic2.md
  images/           # Static assets copied to output

Output Directory

output/
  index.html        # Generated home page
  getting-started.html
  configuration.html
  advanced/
    topic1.html
    topic2.html
  css/             # Styles
  js/              # JavaScript (live reload, search, syntax highlighting)
  pagefind/        # Search index (if search feature enabled)

Features

Syntax Highlighting

Server-side syntax highlighting via syntect. Supports all major languages:

```rust
fn main() {
    println!("Hello, world!");
}
```

```python
def hello():
    print("Hello, world!")
```

Full-Text Search (Pagefind)

Search is built in via Pagefind. Requires pagefind CLI:

# Install pagefind
cargo install pagefind

# Pagefind runs automatically during build
# Manual indexing if needed:
pagefind --site output_dir

Live Reload

When using --serve --watch, pages automatically reload on file changes via WebSocket.

Index Page (Two Methods)

MD-Book supports two ways to create your documentation home page:

Method 1: Custom Content with index.md

Create an index.md file in your input directory for a custom home page:

# Welcome to My Documentation

This is my custom home page content with full markdown support.

## Quick Links

- [Getting Started](getting-started.md)
- [Configuration](configuration.md)
- [API Reference](api/reference.md)

When index.md exists, its content is rendered as the home page. This gives you full control over the layout and content.

Method 2: Auto-Generated Card Navigation

If no index.md is present, MD-Book automatically generates a card-based home page using Shoelace UI components. This displays:

• A "Documentation" header
• Cards for each section/directory
• Cards for each page within sections
• "Read More" buttons linking to each page

This is ideal for quickly getting started or for projects where you want automatic navigation without maintaining a custom index.

Choosing Between Methods:

• Use index.md when you want custom welcome content, specific navigation order, or branded messaging
• Use auto-generated cards for quick setup or when documentation structure should drive navigation

Right-Hand TOC

Each page includes a right-hand table of contents for in-page navigation.

Template Customization

Templates use Tera templating engine:

Template	Purpose
page.html.tera	Individual page layout
index.html.tera	Home page
sidebar.html.tera	Navigation sidebar
header.html.tera	Page header
footer.html.tera	Page footer

Web Components

Built-in Web Components:

• doc-toc.js - Table of contents
• search-modal.js - Search interface
• doc-sidebar.js - Responsive sidebar
• simple-block.js - Content blocks

Deployment

Cloudflare Pages (Recommended)

# Setup
./scripts/setup-cloudflare.sh

# Deploy
./scripts/deploy.sh production

Netlify

# Build
cargo run -- -i docs -o dist

# Deploy
netlify deploy --prod --dir=dist

GitHub Pages

Use the GitHub Actions workflow:

- name: Build site
  run: cargo run -- -i docs -o _site

- name: Deploy to GitHub Pages
  uses: actions/deploy-pages@v4

Other Platforms

Vercel, AWS Amplify, Render, Railway, Fly.io, and DigitalOcean are all supported. See DEPLOYMENT.md for details.

Testing

# Unit tests
cargo test --lib --bins

# Integration tests
cargo test --test integration --features "tokio,search,syntax-highlighting"

# All tests
cargo test --all-targets --features "tokio,search,syntax-highlighting"

# Quality checks
make qa              # Format, clippy, tests
make ci-local        # Simulate CI locally

Feature Flags

# Cargo.toml features
default = ["server", "watcher", "search", "syntax-highlighting"]
server = ["warp", "tokio/full"]           # Dev server with live reload
watcher = ["notify", "tokio/full"]         # File watching
search = ["pagefind"]                      # Pagefind search integration
syntax-highlighting = ["syntect"]          # Code highlighting
wasm = ["wasm-bindgen"]                    # WASM support

Build minimal version:

cargo build --no-default-features

Security Considerations

HTML in Markdown

Raw HTML is disabled by default for security. Enable only if you trust all content:

[output.html]
allow-html = true  # WARNING: Enables XSS risk

Secrets Management

• Use 1Password integration or environment variables
• Never commit .env files
• See docs/1PASSWORD_SETUP.md for secure setup

Common Patterns

Creating Documentation Project

With custom index page:

mkdir docs
cat > docs/index.md << 'EOF'
# Welcome to My Project

This is the home page with custom content.

## Quick Start
See [Getting Started](getting-started.md) to begin.
EOF

cat > docs/getting-started.md << 'EOF'
# Getting Started

Installation and setup instructions.
EOF

md-book -i docs -o output --serve --watch

With auto-generated card navigation:

mkdir docs
# No index.md - cards will be auto-generated

cat > docs/getting-started.md << 'EOF'
# Getting Started

Installation and setup instructions.
EOF

cat > docs/configuration.md << 'EOF'
# Configuration

How to configure the project.
EOF

md-book -i docs -o output --serve --watch
# Home page shows cards linking to all pages automatically

Adding Search

Search works automatically when pagefind is installed:

cargo install pagefind
md-book -i docs -o output  # Search index generated automatically

Custom Styling

Edit CSS in src/templates/css/styles.css or provide custom template directory.

Troubleshooting

Build Fails

# Verify Rust installation
rustc --version
cargo --version

# Clean and rebuild
cargo clean
cargo build --release

Search Not Working

# Verify pagefind installed
which pagefind

# Manually run indexing
pagefind --site output_dir

Live Reload Not Working

Ensure using both flags together:

md-book -i docs -o output --watch --serve

Repository

• GitHub: https://github.com/terraphim/md-book
• Issues: https://github.com/terraphim/md-book/issues
• Discussions: https://github.com/terraphim/md-book/discussions