静态站 & 文档生成器

这个 pack 装了什么

这个包收齐了 五个静态站框架，扛过了 JS 框架轮换大潮，到 2026 年还能作为默认选项。是有立场的清单：里面没有「从 markdown 文件生成 HTML」的玩具项目 —— 每个条目都有真实插件生态、搜索方案、可部署的生产配置。

这套覆盖四种形态：开发者文档（VitePress / Docusaurus）、漂亮的营销页（Astro）、托管文档即服务（Mintlify）、工程师真愿意做的 PPT（Slidev）。一个 pack 四种产物 —— 按受众挑。

为什么是这套

静态站回潮是因为替代方案太贵了。营销页用服务端渲染的 Next.js，比 build 时生成 HTML 在算力和复杂度上贵太多。这五个生成器都做同一件事：拿 markdown（或 MDX）+ 少量配置，吐静态 HTML，挂任何 CDN 都能跑。

差别：

• VitePress 自带 docs 主题，开箱就好看。Vue / Vite / Vitest 自己都在用 —— 强 dogfood 信号
• Astro 最广。能做文档站，也能做落地页 / 博客 / 小营销站。Islands 架构意味着除非组件主动 opt-in，否则零 JS
• Mintlify 是唯一托管的。你写 markdown 推 GitHub，Mintlify 帮你托管在 <你>.mintlify.app（或自己域名）。是自跑 Docusaurus 的 SaaS 替代
• Docusaurus 最重，但插件最多 —— 版本化文档、i18n、搜索、博客全是一等公民。需要跨大版本管理文档时选它
• Slidev 是黑马。markdown 驱动的 PPT，带代码高亮、交互组件、演讲者备注。讨厌 Keynote 的工程师爱它

一条命令装齐

# 装整个 pack，把每个 builder 的 starter 模板放进项目
tokrepo install pack/static-site-docs

# 或单装
tokrepo install vitepress
tokrepo install astro
tokrepo install docusaurus

TokRepo CLI 把每个框架脚手架到 sites/<框架>/，方便对比产物再下决心。五个都带 .tokrepo/ 笔记文件，里面写了我们验证过的生产部署目标（Vercel / Cloudflare Pages / Netlify / GitHub Pages）。

几个常见坑

• VitePress 锁 Vue，自定义组件必须 Vue。如果你团队纯 React，VitePress 会很难受 —— React 选项是 Docusaurus 或 Mintlify
• Astro 的 MDX 水合是 opt-in 的，<Counter client:load /> 会发 JS，纯 <Counter /> 不会。忘了 client:* 是「为什么我的按钮不动」头号 bug
• Mintlify 意味着 SaaS 锁定，内容是你的（都是 markdown 在你 repo），但渲染 / 搜索 / 分析在 Mintlify 云。投入前先想好导出路径
• Docusaurus 多版本文档是单向的，一旦切了 2.0 版，回过去改老版本很别扭。慎重决定何时上版本号
• Slidev 不是 slides.dev，它是你的 repo。托管自己搞（Vercel 够用）。开会前 5 分钟别拿 localhost URL 给 CEO 看

常见误解

「静态 = 死的」是迷思。五个框架都支持水合 / 服务函数 / 混合渲染来处理需要动的部分。Astro 可以按路由 opt-in SSR；Docusaurus 在浏览器跑 React 做交互；VitePress 任何需要的页面都能跑 Vue。默认「发 HTML」，逃生通道是「在值得的位置发 JS」。

「所有静态站生成器都一样」也是错的。VitePress vs Docusaurus 决定谁能给你文档贡献（Vue 党 vs React 党）。Astro vs Mintlify 决定谁拥有部署管道（你 vs Mintlify）。要主动选。