ワンクリックで
md-book
MD-Book documentation generator skill. Use when working with MD-Book, a modern mdbook replacement for generating HTML documentation from Markdown files. Supports syntax highlighting, live reload, Pagefind search, and Tera templates.
メニュー
MD-Book documentation generator skill. Use when working with MD-Book, a modern mdbook replacement for generating HTML documentation from Markdown files. Supports syntax highlighting, live reload, Pagefind search, and Tera templates.
Secure secret management using 1Password CLI. Detect plaintext secrets in files and codebases, convert environment files to 1Password templates, inject secrets securely using op inject, and audit codebases for security compliance.
Comprehensive Caddy web server management across multiple environments. Handles multi-server operations, zero-downtime deployments, secret management with 1Password, custom builds with plugins, and systemd service management.
Generates Rust code for GPUI desktop UI components following Zed editor patterns. Use when building desktop applications with gpui crate, creating themed UI components, implementing autocomplete/completions, building command palettes, or working with the gpui-component library. Covers RenderOnce components, Entity state management, theming with ActiveTheme, and Zed-style UI patterns.
Phase 2 of disciplined development. Creates implementation plans based on approved research. Specifies file changes, function signatures, test strategy, and step sequence. Requires human approval before implementation.
Phase 3 of disciplined development. Executes approved implementation plans step by step. Each step includes tests, follows the design exactly, and produces reviewable commits.
Phase 1.5/2.5 of disciplined development. Evaluates document quality using the KLS (Krogstie-Lindland-Sindre) 6-dimension framework. Produces structured ratings, identifies gaps, suggests specific revisions, and blocks phase transitions when quality is below threshold. Applies to Phase 1 research docs and Phase 2 design docs.
| name | md-book |
| description | MD-Book documentation generator skill. Use when working with MD-Book, a modern mdbook replacement for generating HTML documentation from Markdown files. Supports syntax highlighting, live reload, Pagefind search, and Tera templates. |
| license | Apache-2.0 |
Use this skill when working with MD-Book, a modern mdbook replacement for generating HTML documentation from Markdown files.
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.
# 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
| 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) |
# 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
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
# 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
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/
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)
Server-side syntax highlighting via syntect. Supports all major languages:
```rust
fn main() {
println!("Hello, world!");
}
```
```python
def hello():
print("Hello, world!")
```
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
When using --serve --watch, pages automatically reload on file changes via WebSocket.
MD-Book supports two ways to create your documentation home page:
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.
If no index.md is present, MD-Book automatically generates a card-based home page using Shoelace UI components. This displays:
This is ideal for quickly getting started or for projects where you want automatic navigation without maintaining a custom index.
Choosing Between Methods:
Each page includes a right-hand table of contents for in-page navigation.
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 |
Built-in Web Components:
doc-toc.js - Table of contentssearch-modal.js - Search interfacedoc-sidebar.js - Responsive sidebarsimple-block.js - Content blocks# Setup
./scripts/setup-cloudflare.sh
# Deploy
./scripts/deploy.sh production
# Build
cargo run -- -i docs -o dist
# Deploy
netlify deploy --prod --dir=dist
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
Vercel, AWS Amplify, Render, Railway, Fly.io, and DigitalOcean are all supported. See DEPLOYMENT.md for details.
# 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
# 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
Raw HTML is disabled by default for security. Enable only if you trust all content:
[output.html]
allow-html = true # WARNING: Enables XSS risk
.env filesdocs/1PASSWORD_SETUP.md for secure setupWith 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
Search works automatically when pagefind is installed:
cargo install pagefind
md-book -i docs -o output # Search index generated automatically
Edit CSS in src/templates/css/styles.css or provide custom template directory.
# Verify Rust installation
rustc --version
cargo --version
# Clean and rebuild
cargo clean
cargo build --release
# Verify pagefind installed
which pagefind
# Manually run indexing
pagefind --site output_dir
Ensure using both flags together:
md-book -i docs -o output --watch --serve