文档框架选型
文档框架选型
Section titled “文档框架选型”文档框架的选择直接决定了开发体验、站点性能和长期可维护性。本节对比主流方案，解释我们为何最终选定 Astro + Starlight。
Q：文档框架主要有哪些类别？
Section titled “Q：文档框架主要有哪些类别？”A：文档工具可分为四大类：
| 类别 | 代表工具 | 优势 | 劣势 |
|---|---|---|---|
| 静态站点生成器 (SSG) | Astro、Next.js、Hugo、Jekyll | 完全控制、速度快、免费托管 | 需要开发能力 |
| 文档专用框架 | Starlight、Docusaurus、VitePress、MkDocs | 内置文档特性（侧边栏、搜索、i18n） | 非文档页面的灵活性较低 |
| 托管平台 | GitBook、ReadMe、Notion Sites | 零配置、所见即所得编辑 | 厂商锁定、定制有限、付费 |
| Wiki 系统 | MediaWiki、BookStack | 协作编辑 | UI 老旧、SEO 差、笨重 |
Q：为什么不选 Docusaurus 或 VitePress？
Section titled “Q：为什么不选 Docusaurus 或 VitePress？”A：两者都是优秀选择，以下是直接对比：
| 特性 | Starlight (Astro) | Docusaurus | VitePress |
|---|---|---|---|
| 框架 | Astro（框架无关） | React | Vue |
| 包体积 | 最小（默认不发送 JS） | 较大（React 运行时） | 小（Vue 运行时） |
| 国际化 | 内置语言路由 | 基于插件 | 手动配置 |
| 搜索 | Pagefind（内置，本地） | Algolia DocSearch（外部服务） | VitePress 搜索或 MiniSearch |
| 内容格式 | Markdown + MDX | 仅 MDX | Markdown + Vue |
| 性能 | 优秀（静态优先） | 良好 | 优秀 |
| 生态 | 快速增长 | 成熟 | 快速增长 |
我们选择 Starlight 的理由：
- 默认零 JavaScript：Starlight 输出纯 HTML/CSS，仅在需要交互组件时加载 JS，意味着更快的页面加载和更好的 SEO。
- 框架无关：如果需要交互组件，可以使用 React、Vue、Svelte 或任何框架——无锁定。
- 内置 i18n：语言路由和语言切换开箱即用。
- Content Collections：Astro 的类型化内容系统在构建时捕获 schema 错误。
- Pagefind：本地构建时搜索，不依赖外部服务。
Q：什么时候应该选择托管平台？
Section titled “Q：什么时候应该选择托管平台？”A：托管平台（GitBook、ReadMe）适用于以下场景：
- 团队没有 Web 开发能力
- 需要非技术写作者进行协作编辑
- 愿意按月付费换取便利
- 不需要深度定制或自定义构建流程
对于大多数技术团队，自托管 SSG 方案以更低成本提供更多控制力。
Q：选错了框架以后能迁移吗？
Section titled “Q：选错了框架以后能迁移吗？”A：可以，但成本因情况而异：
- 基于 Markdown 的框架（Starlight、VitePress、MkDocs）：迁移相对容易，内容是标准 Markdown + frontmatter。
- 重度使用 MDX 的框架（Docusaurus）：需要将 JSX 组件转换回标准 Markdown。
- 托管平台：导出选项各异；部分平台将内容锁定在私有格式中。
最稳妥的做法是保持内容为标准 Markdown 加清晰的 frontmatter——这样切换框架时工作量最小。
对于一个小型团队构建技术文档，需求包括：
- 快速且 SEO 友好
- 多语言支持
- 版本控制
- 免费托管
Astro + Starlight 是一个出色的选择。下一节我们将从零开始搭建项目。
正在开发商业 IoT 产品？
我们提供 ESP32 ODM 定制设计与制造服务。从原型到量产——编写这套教程的团队，可以和你一起实现。
联系我们 →