docs-site-weapon

name

docs-site-weapon

description

Documentation-site infrastructure specialist — platform selection (Docusaurus v3/v4, Mintlify, GitBook, MkDocs Material, Nextra v4, Starlight/Astro, Fern), the Diátaxis content pyramid, docs-as-code CI pipelines, and search setup (Algolia DocSearch, pagefind). Use when the user says "pick a docs platform", "set up Docusaurus", "migrate from GitBook", "add search to our docs", "docs-as-code CI", "Mintlify vs Starlight", or invokes `docs-site-guardian`. Do NOT use for OpenAPI spec enrichment or SDK generation (api-docs-guardian), internal knowledge-base authoring (library-guardian), or marketing website builds (website-guardian).

docs-site Weapon

Opinionated playbook for docs-site-guardian. Equips the Angel to select, set up, and maintain developer-facing documentation sites in 2026.

2026 Platform Landscape at a Glance

Platform	Status	Best for	Verdict
Starlight (Astro)	Active, v0.38+, 200K+ weekly downloads	Greenfield open-source / developer docs	Recommend for new projects
Docusaurus v3.10	v3.x final release; v4 incoming (React 19)	Complex versioned docs with React components	Recommend; enable v4 flags now
Mintlify	Active; headless mode (Enterprise, Feb 2026)	API-first managed docs with fast time-to-ship	Recommend with pricing caveat
MkDocs Material	MAINTENANCE MODE (Nov 2025)	Python projects already on MkDocs	Do NOT recommend for new projects
Nextra v4	Active, App Router-based	Next.js teams wanting docs in same repo	Recommend for JS monorepos
GitBook	Active, per-site pricing	Non-technical authors, block editor UX	Recommend for mixed-audience docs
Fern	Active; MCP + llms.txt auto-gen 2026	API-first docs + SDK generation combined	Recommend for API portals

Critical 2026 finding: MkDocs Material entered maintenance mode in November 2025. No new features; security fixes only until November 2026. Do NOT start new projects on MkDocs Material. Existing users can evaluate Zensical (successor, no public release date yet). Source: research/external/2026-05-20-mkdocs-material-maintenance-mode.md.

Entry point for any invocation

1. Read guides/00-platform-selection.md — the scored decision tree. Always run this first when the platform is undecided.
2. Read guides/01-content-pyramid.md — the Diátaxis model for structuring documentation content.
3. Read the platform-specific guide for the chosen tool (guides/04- through guides/09-).
4. Read guides/02-docs-as-code.md for CI/lint/preview setup.
5. Read guides/03-search.md for search configuration.

Folder layout

docs-site-weapon/
├── SKILL.md                          (this file — master index)
├── README.md                         (one-page human overview)
├── guides/
│   ├── 00-platform-selection.md      (scored decision tree; run first)
│   ├── 01-content-pyramid.md         (Diátaxis: tutorial/how-to/reference/explanation)
│   ├── 02-docs-as-code.md            (Vale, lychee, PR preview, CI pipeline)
│   ├── 03-search.md                  (DocSearch vs pagefind vs built-in)
│   ├── 04-docusaurus.md              (Docusaurus v3.10 + v4-ready setup)
│   ├── 05-mintlify.md                (Mintlify setup, 2026 pricing, headless mode)
│   ├── 06-mkdocs-material.md         (maintenance mode guidance, migration paths)
│   ├── 07-starlight.md               (Starlight v0.38+, Astro v6)
│   ├── 08-nextra.md                  (Nextra v4, App Router)
│   └── 09-fern.md                    (Fern, MCP server, llms.txt)
├── examples/
│   ├── happy-path-starlight-setup.md  (greenfield Starlight docs site from zero)
│   └── migration-gitbook-to-starlight.md (GitBook → Starlight migration)
├── templates/
│   ├── platform-selection-matrix.md   (scored matrix stub to fill in)
│   ├── docs-site-setup-checklist.md   (launch checklist)
│   └── migration-checklist.md         (source-to-target migration steps)
├── reports/
│   └── README.md                      (how past-run reports accumulate)
└── research/                          (populated by scripture-historian — DO NOT MODIFY)
    ├── research-plan.md
    ├── research-summary.md
    ├── index.md
    ├── external/  (12 source notes)
    └── internal/  (2 source notes)

Critical directives

• Always check platform status before recommending. MkDocs Material is in maintenance mode as of Nov 2025 (research/external/2026-05-20-mkdocs-material-maintenance-mode.md). Docusaurus v4 is incoming; start v3.10 with future flags. Do not recommend stale platforms without flagging the risk.
• Run the decision tree before picking a platform. Platform selection without scoring the team's actual constraints (content type, hosting model, cost, customization depth) produces the wrong answer. See guides/00-platform-selection.md.
• Default to docs-as-code. PR-gated, lint-checked, preview-deployed documentation is the minimum. See guides/02-docs-as-code.md.
• Treat search as required, not optional. An undiscoverable docs site is worse than no docs site. See guides/03-search.md.
• Route OpenAPI concerns to api-docs-guardian. Docs-site-guardian wires the reference section into the site but does not author OpenAPI specs or SDK generation.