Static Site & Docs Builders

What's in this pack

This pack collects the five static-site frameworks that have outlasted the JS framework churn and ship enough features to be a default choice in 2026. The list is opinionated: nothing here is a "we generate HTML from a single Markdown file" hobby project — every entry has a real plugin ecosystem, a search story, and a deployable production setup.

The set covers four shapes: developer documentation (VitePress, Docusaurus), polished marketing pages (Astro), hosted docs-as-a-service (Mintlify), and presentations engineers actually want to give (Slidev). One pack, four output formats — pick the one that fits your audience.

Why this stack

Static sites are back because the alternatives proved expensive. Server-rendered Next.js for marketing pages costs more in compute and complexity than just generating HTML at build time. These five generators all do the same thing: take Markdown (or MDX) plus a small amount of config, and output static HTML you can host on any CDN.

Where they differ:

• VitePress ships a "docs" theme that looks correct out of the box. Used by Vue, Vite, Vitest themselves — strong dogfood signal.
• Astro is the broadest. It can build a docs site, but it can also build a landing page, a blog, a small marketing site. The "Islands" architecture means you ship zero JS unless a component opts in.
• Mintlify is the only hosted entry. You write Markdown, push to GitHub, and Mintlify hosts the rendered docs at <your>.mintlify.app (or your own domain). It's a SaaS replacement for self-running Docusaurus.
• Docusaurus is the heaviest but has the most plugins — versioned docs, i18n, search, blog, all first-class. Pick it when you need versioning across major releases.
• Slidev is the wild card. Markdown-driven slide decks with code highlighting, interactive components, and presenter notes. Engineers who hate Keynote love it.

Install in one command

# Install the pack — drops a starter template for each builder into your project
tokrepo install pack/static-site-docs

# Or pick one
tokrepo install vitepress
tokrepo install astro
tokrepo install docusaurus

The TokRepo CLI scaffolds each framework into sites/<framework>/ so you can compare output and pick a winner before committing. All five include a .tokrepo/ notes file with the production deploy targets we've validated (Vercel, Cloudflare Pages, Netlify, GitHub Pages).

Common pitfalls

• VitePress is Vue-locked. Custom components must be Vue. If your team is React-only, VitePress will feel hostile — Docusaurus or Mintlify are the React options.
• Astro's MDX hydration is opt-in. A <Counter client:load /> ships JS; a plain <Counter /> doesn't. Forgetting client:* is the #1 "why doesn't my button work" bug.
• Mintlify means SaaS lock-in. Your content is yours (it's all Markdown in your repo) but the rendering, search, and analytics live in Mintlify cloud. Plan an export path before you commit.
• Docusaurus versioned docs is one-way. Once you cut version 2.0 docs, retroactively editing them is awkward. Be deliberate about when to version.
• Slidev decks are not slides.dev.com. They're your repo. Hosting is on you (Vercel works fine). Don't try to share a localhost URL with your CEO five minutes before a board meeting.

Common misconceptions

"Static means dead" is a myth. All five frameworks support hydration, server functions, or hybrid rendering for the parts that need them. Astro can opt into SSR per route; Docusaurus has client-side React for interactivity; VitePress runs Vue in the browser for any page that needs it. The default is "ship HTML"; the escape hatch is "ship JS where it earns its weight."

"All static site generators are the same" is also wrong. The choice between VitePress and Docusaurus shapes who can contribute to your docs (Vue people vs React people). The choice between Astro and Mintlify shapes who owns the deploy pipeline (you vs Mintlify). Pick deliberately.