Skip to content

Documentation Site Generator Research

Goal: Turn our docs/ folder of markdown runbooks, SOPs, and operational documents into a browsable, searchable docs site with minimal maintenance overhead.

Date: 2026-02-26

Executive Summary

After evaluating six documentation site generators, MkDocs with Material theme is the clear recommendation for our use case. It offers zero-config markdown rendering, automatic navigation from folder structure, built-in search and dark mode, trivial deployment to Cloudflare Pages, and zero cost. Its Python-based toolchain is simpler than Node/React alternatives, and it requires the least ongoing maintenance for a solo operator.

Tool Evaluations

1. MkDocs + Material Theme

What it is: A Python-based static site generator with the Material theme providing a polished, feature-rich documentation experience. As of v9.7.0 (Nov 2025), all previously paid "Insiders" features are now free.

Setup complexity: Minimal. Install via pip install mkdocs-material, create a mkdocs.yml config file, point it at your docs/ folder, done. No Node.js, no React, no build toolchain beyond Python.

Pros: - Renders standard markdown files with zero modifications needed - Automatic navigation generated from folder structure - Built-in client-side search (lunr-based, works offline) - Dark/light mode toggle out of the box with automatic OS detection - Excellent mobile responsive design - SPA-like instant navigation between pages - Massive plugin ecosystem (300+ plugins) - All features now free (Insiders features merged into community edition) - Native Cloudflare Pages and GitHub Pages support - Single YAML config file -- no JavaScript/TypeScript knowledge needed - Instant previews, search suggestions, search highlighting - Active community, 50,000+ users

Cons: - Entering maintenance mode; successor project (Zensical) is in development - No native versioning (requires mike plugin) - No native i18n (requires plugins) - Python dependency (though minimal)

Cost: Free. No paid tiers remain.

Deploy: First-class support for both Cloudflare Pages and GitHub Pages. Cloudflare has a built-in MkDocs framework preset.

2. Docusaurus

What it is: A React-based static site generator from Meta (Facebook), designed for open-source project documentation.

Setup complexity: Moderate. Requires Node.js and npm. Scaffolded via npx create-docusaurus. Config is JavaScript-based. Understanding React/JSX is helpful for customization.

Pros: - Sidebar auto-generation from folder structure - Native versioning support (no plugin needed) - Native i18n support - MDX support (embed React components in markdown) - Large community, backed by Meta - Free and open-source (MIT)

Cons: - Requires Node.js/React ecosystem knowledge for anything beyond basics - Heavier build toolchain (node_modules, webpack/babel) - Steeper learning curve for a solo operator - Markdown files may need frontmatter adjustments for sidebar ordering - Config is JavaScript, not simple YAML - Slower builds compared to simpler tools

Cost: Free.

Deploy: Static output works on any host. GitHub Pages and Cloudflare Pages both supported, but requires more build config than MkDocs.

3. GitBook

What it is: A hosted documentation platform with a web editor and Git sync capability.

Setup complexity: Low for the web editor. Git sync requires connecting your GitHub/GitLab repo.

Pros: - Polished, professional-looking output with zero effort - Git sync (edit in repo, auto-publishes) - Real-time collaborative editing - AI-powered search on paid plans - Good mobile experience

Cons: - Free tier limited to 1 user, gitbook.io subdomain only - Custom domain requires Premium ($65/month) - Per-site pricing with per-user add-ons ($12/month per additional user) - Vendor lock-in concerns -- content tied to their platform - No self-hosted option - Steep price jump from free to paid ($0 to $65/month) - Has shifted policies in the past, requiring upgrades to edit existing content

Cost: Free tier is very limited. Premium is $65/month. Not practical for our use case when free alternatives are superior.

Deploy: Hosted by GitBook. No self-deploy option.

4. Mintlify

What it is: An AI-native documentation platform focused on API docs, backed by a16z.

Setup complexity: Low. Git-based workflow with auto-deploy on push. CLI available for local preview.

Pros: - Modern, beautiful design out of the box - Free tier includes custom domain - Git sync workflow (edit markdown, push, auto-deploys) - API playground built-in - AI-powered search on paid plans - Used by Anthropic, Zapier, Perplexity

Cons: - Focused on API documentation -- overkill for internal runbooks/SOPs - Free tier limited to 1 editor with no AI features - Jump to Pro is $300/month -- wildly expensive for our needs - Vendor lock-in to Mintlify's hosting platform - MDX-based, may require file format changes - AI message overages add costs ($30-100/month on top of Pro) - Seat-based pricing scales poorly

Cost: Free (Hobby) plan is limited. Pro is $300/month. Not cost-effective for internal docs.

Deploy: Hosted by Mintlify. Deploys to .mintlify.app subdomain or custom domain.

5. Starlight (Astro)

What it is: A documentation framework built on Astro, a modern web framework known for shipping zero JavaScript by default.

Setup complexity: Moderate. Requires Node.js. Scaffolded via npm create astro -- --template starlight. Content goes in src/content/docs/ (not a top-level docs/ folder). Config is astro.config.mjs.

Pros: - Excellent performance (ships minimal JavaScript) - Built-in search via Pagefind (no external services) - Dark/light mode out of the box - Sidebar auto-generation via autogenerate config directive - Markdown, Markdoc, and MDX support - Framework-agnostic component support (React, Vue, Svelte) - Accessible by default - TypeScript frontmatter validation - Free and open-source

Cons: - Requires moving files to src/content/docs/ (can't point at existing docs/) - Still technically beta software with frequent breaking changes - Requires Node.js ecosystem - Astro-specific concepts to learn (content collections, integrations) - Config is JavaScript/TypeScript, not YAML - Smaller community than MkDocs or Docusaurus

Cost: Free.

Deploy: Static output. Works on Cloudflare Pages and GitHub Pages.

6. VitePress

What it is: A lightweight, Vue-based static site generator powered by Vite. Used by the official Vue.js and Vite documentation.

Setup complexity: Low-moderate. Requires Node.js. Simple npm add -D vitepress setup. Config is JavaScript/TypeScript.

Pros: - Extremely fast hot-reload during development (<100ms) - Lightweight compared to Docusaurus - Vue component support in markdown - Good markdown extensions (GitHub-flavored alerts, code highlighting) - SPA navigation for subsequent page loads - Vite-powered build (fast)

Cons: - No built-in auto-sidebar from folder structure (requires community plugin vitepress-sidebar) - Vue.js knowledge helpful for customization - Requires Node.js - Smaller ecosystem than MkDocs or Docusaurus - Dark mode requires manual theme config - Config is JavaScript, not YAML

Cost: Free.

Deploy: Static output. Works on any static host including Cloudflare Pages and GitHub Pages.

Comparison Matrix

Scoring: 1 (poor) to 5 (excellent)

Criterion MkDocs Material Docusaurus GitBook Mintlify Starlight VitePress
Zero-config markdown 5 3 4 3 3 4
Auto-navigation 5 4 4 3 4 2
Built-in search 5 4 3* 3* 5 4
Dark mode 5 4 4 5 5 3
Mobile UX 5 5 5 5 5 4
Deploy simplicity 5 3 5** 5** 4 4
Maintenance burden 5 3 4 3 3 3
Cost (free tier) 5 5 2 2 5 5
Total 40 31 31 29 34 29

* GitBook and Mintlify have AI-powered search on paid plans only; basic search on free tier. ** Hosted platforms -- deploy is simple but you lose control.

Scoring Notes

  • Zero-config markdown: Can it render our existing .md files without modifications? MkDocs Material reads standard markdown from a docs/ folder with zero changes needed. Docusaurus and Starlight may need frontmatter additions. Mintlify uses MDX conventions.
  • Auto-navigation: MkDocs auto-generates sidebar from folder structure with no config. Docusaurus does too but may need sidebar_position frontmatter for ordering. VitePress needs a plugin.
  • Built-in search: MkDocs Material and Starlight have the best built-in search (lunr and Pagefind respectively). No external services needed.
  • Deploy simplicity: Cloudflare Pages has a native MkDocs preset. GitHub Pages is a one-command mkdocs gh-deploy.
  • Maintenance burden: MkDocs requires essentially zero maintenance once set up. Single YAML file. No node_modules. No lock files. No framework upgrades to chase.

Recommendation: MkDocs + Material Theme

For a solo operator managing internal runbooks and SOPs in markdown, MkDocs Material is the best choice by a significant margin.

Why MkDocs Material Wins

  1. Zero friction with existing content: Point it at your docs/ folder and it works. No file moves, no frontmatter changes, no format conversions.

  2. Simplest toolchain: Python + pip. No Node.js, no React, no webpack, no node_modules. A requirements.txt with one line: mkdocs-material.

  3. Minimal config: A single mkdocs.yml file (10-20 lines) configures everything. Compare to JavaScript config files that can grow to hundreds of lines.

  4. Everything built-in: Search, dark mode, mobile responsiveness, navigation, breadcrumbs -- all work out of the box with zero plugins needed.

  5. Free: All features are now free as of v9.7.0. No paid tiers, no feature gates, no per-seat pricing.

  6. Trivial deployment: Cloudflare Pages has a native preset. Push to GitHub, site rebuilds automatically.

  7. Low maintenance: No dependency churn. No framework major versions to migrate. Edit markdown, push, done.

The Maintenance Mode Caveat

MkDocs Material entered maintenance mode in November 2025 as the creator shifts focus to Zensical (the successor project). Critical bugs and security issues will be fixed for at least 12 months. This is actually fine for our use case: - The tool is mature and feature-complete for documentation sites - We need stability, not bleeding-edge features - Zensical will be able to read mkdocs.yml files, providing a migration path if needed - Static site generators do not have the same update urgency as web frameworks

Quick-Start Instructions

Prerequisites

  • Python 3.8+ (pre-installed on macOS)
  • pip

1. Install MkDocs Material

pip install mkdocs-material

2. Create Configuration

Create mkdocs.yml in the repo root:

site_name: Research Relay Operations
site_description: Internal runbooks, SOPs, and operational documentation

theme:
  name: material
  palette:
    # Light mode
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    # Dark mode
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  features:
    - navigation.instant
    - navigation.instant.prefetch
    - navigation.tabs
    - navigation.sections
    - navigation.expand
    - navigation.path
    - navigation.top
    - navigation.footer
    - search.suggest
    - search.highlight
    - search.share
    - toc.follow

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - toc:
      permalink: true

plugins:
  - search

nav:
  - Home: index.md
  - Control Plane: CONTROL_PLANE.md
  - Entity:
      - entity/selections.md
      - entity/ca-llc-requirements.md
      - entity/name-risk-check.md
      - entity/registered-agent-options.md
      - entity/virtual-address-options.md
  - Orchestration:
      - orchestration/AI_AGENT_ORCHESTRATION_PLAN.md
      - orchestration/AGENT_ROLES.md
      - orchestration/HUMAN_GATES.md
      - orchestration/PHASE_BOARD.md

Alternative: Auto-generated navigation (no explicit nav section needed):

# Remove the `nav:` section entirely.
# MkDocs will auto-generate navigation from folder structure.
# Files are sorted alphabetically, folders become sections.

3. Create a Landing Page

Create docs/index.md:

# Research Relay Operations

Internal documentation, runbooks, and standard operating procedures.

## Sections

- **Entity** -- LLC formation research and selections
- **Orchestration** -- Agent roles, human gates, phase board
- **Banking** -- Bank options and risk notes
- **Accounting** -- Accounting stack, crypto policy
- **Compliance** -- RUO disclosures, ToS, privacy policy
- **Ops** -- SOPs for fulfillment, refunds, support
- **Payments** -- BTCPay, ACH, card processing
- **Privacy** -- Comms stack, identity separation
- **Automation** -- Automation runbooks

4. Preview Locally

mkdocs serve
# Opens at http://127.0.0.1:8000 with live reload

5. Build Static Site

mkdocs build
# Output in site/ directory

Example: Folder-to-Navigation Mapping

Our current docs/ structure maps directly to site navigation:

docs/                          Site Navigation
 |                              |
 +-- index.md            -->   Home
 +-- CONTROL_PLANE.md    -->   Control Plane
 |
 +-- entity/             -->   Entity (section)
 |   +-- selections.md         +-- Selections
 |   +-- ca-llc-req...         +-- CA LLC Requirements
 |   +-- name-risk...          +-- Name Risk Check
 |   +-- registered...         +-- Registered Agent Options
 |   +-- virtual-a...          +-- Virtual Address Options
 |
 +-- orchestration/      -->   Orchestration (section)
 |   +-- AI_AGENT_...          +-- AI Agent Orchestration Plan
 |   +-- AGENT_ROLES.md        +-- Agent Roles
 |   +-- HUMAN_GATES.md        +-- Human Gates
 |   +-- PHASE_BOARD.md        +-- Phase Board
 |
 +-- banking/            -->   Banking (section)
 +-- accounting/         -->   Accounting (section)
 +-- compliance/         -->   Compliance (section)
 +-- ops/                -->   Ops (section)
 +-- payments/           -->   Payments (section)
 +-- privacy/            -->   Privacy (section)
 +-- automation/         -->   Automation (section)

MkDocs auto-generates page titles from the first # Heading in each file, or from the filename if no heading is present. Section names come from folder names (capitalized automatically by Material theme).

To control ordering, either: 1. Use an explicit nav: section in mkdocs.yml (full control, must update when adding files) 2. Prefix filenames with numbers: 01-selections.md, 02-ca-llc-requirements.md (auto-nav respects alphabetical order) 3. Use the awesome-pages plugin for per-folder .pages files that control order

Deploy Instructions

  1. Push repo to GitHub (already done).

  2. Go to Cloudflare Dashboard > Workers & Pages > Create > Pages > Connect to Git.

  3. Select the repository and configure build settings:

  4. Framework preset: MkDocs (auto-detected)
  5. Build command: mkdocs build
  6. Build output directory: site

  7. Environment variable: PYTHON_VERSION = 3.11

  8. Click Save and Deploy.

  9. Site deploys to <project>.pages.dev. Add a custom domain from the Cloudflare dashboard if desired.

Automatic rebuilds: Every push to the main branch triggers a rebuild. Pull requests get preview deployments automatically.

Cost: Cloudflare Pages free tier allows 500 builds/month and unlimited bandwidth.

Option B: GitHub Pages

  1. Create .github/workflows/deploy.yml:
name: Deploy docs
on:
  push:
    branches: [main]

permissions:
  contents: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force

  1. In GitHub repo Settings > Pages, set source to "Deploy from a branch" and branch to gh-pages.

  2. Site deploys to <username>.github.io/<repo>.

Cost: Free for public and private repos.

Dependencies File

Create requirements.txt in the repo root:

mkdocs-material==9.7.2

This pins the version and ensures reproducible builds across local development and CI/CD.

Optional Enhancements

These are not needed for the initial setup but can be added later:

Enhancement Plugin/Config Purpose
Per-folder nav control mkdocs-awesome-pages-plugin Control page order with .pages files per directory
Last updated dates mkdocs-git-revision-date-localized-plugin Show "last updated" on each page from git history
PDF export mkdocs-print-site-plugin Generate printable/PDF versions
Mermaid diagrams pymdownx.superfences + custom fence Render flowcharts and diagrams in markdown
Tags Built-in tags plugin Tag pages for cross-referencing
Privacy/offline Built-in privacy plugin Self-host external assets for privacy compliance

Sources