Docbase 的告别信：一个 Markdown 文档站的落幕，以及平滑迁移 Gatsby 的路线图
Docbase 的告别信一个 Markdown 文档站的落幕以及平滑迁移 Gatsby 的路线图【免费下载链接】DocbaseTurn .md docs into beautiful sites项目地址: https://gitcode.com/gh_mirrors/do/Docbase如果你正在寻找Docbase——那个能把 Markdown 文档一键变成带版本切换、目录菜单和全文搜索的漂亮文档站的开源工具——请先读这封告别信官方已宣布停止积极维护 Docbase并推荐用户平滑迁移到 Gatsby。本文带你回忆它曾经的能力并给出一条清晰的迁移路线图。一、Docbase 是什么让 Markdown 变成文档站的一键魔法Docbase 的定位用一句话概括Turn .md docs into beautiful sites把 .md 文档变成精美的网站。它的核心能力包括多版本文档在v1.0和v2.0之间自由切换示例文档就放在docs/v1.0/与docs/v2.0/目录下自动渲染菜单按文件夹 → 文件两级结构生成侧边导航离线全文搜索通过search-index.json提供实时检索三种内容来源本地文件、GitHub 仓库或任意 HTTP 服务配置写在docbase.json里⚡一键启动配合 yeoman 生成器执行yo docbase几秒后本地文档站就能在浏览器打开当年用它搭起来的站点遍布各大开源项目Airbnb JS 风格指南、Redis 文档等是早期Markdown 文档站方案里的明星。二、为什么说再见停止维护的三个真实原因README.md 里那句We are no longer actively maintaining Docbase, we instead recommend using gatsbyjs背后其实是三个绕不开的事实1. 技术栈年久失修翻看 GruntFile.js 的构建配置和 package.json 会发现Docbase 深度依赖 jQuery、AngularJS、Grunt、PhantomJS 和 bowernode引擎要求还停留在0.8。这些工具大多已停止迭代新开发者几乎无从接手。2. 静态站点生态早已换代Docbase 是 2015 年 2 月发布 v0.0.1 的老项目README 的 History 章节记录了 54 次发布。而 Gatsby 带来了 React 组件化、GraphQL 数据层和上千个官方插件单页应用式文档站已被静态站点生成器SSG全面超越。3. 官方主动让位与其让它带着隐患继续跑不如明确推荐迁移。这是对一个老项目最负责任的做法也是对用户最诚实的告别。三、平滑迁移 Gatsby 的五步路线图 ️好消息是Docbase 的文档是纯 Markdown 纯文件夹结构资产 100% 可携带迁移成本远低于你想象的。第 1 步盘点你的 Markdown 资产先把docs/目录完整备份。如果想查阅 Docbase 当年的配置与行为可以克隆仓库存档git clone https://gitcode.com/gh_mirrors/do/Docbase重点核对docbase.json中的versions映射——它记录了每个版本、每个文件夹、每个文件的展示名称是迁移导航菜单的蓝图。第 2 步让 Gatsby 读懂同样的文件Docbase 的文档结构docs/v1.0/folder1/file1.md这类路径与 Gatsby 完全兼容。用官方插件gatsby-source-filesystem指向docs/目录再用gatsby-transformer-remark解析原来的.md文件一行都不用改即可入库。第 3 步重建版本切换与侧边菜单Docbase 靠docbase.json手工声明版本树Gatsby 则更优雅用 frontmatter 给每篇文档加version: v2.0字段用 GraphQL 按目录/版本过滤自动生成侧边导航版本切换器变成一个普通的 React 组件甚至能加仅显示变更这类新体验第 4 步补上全文搜索Docbase 的离线搜索依赖预生成的search-index.json。迁移后Gatsby 生态里有现成方案构建期生成搜索索引或接入 Algolia、InstantSearch搜索体验还能比当年更好。第 5 步部署上线Docbase 时代靠 Travis GitHub Pages 发布现在 Gatsby 的构建产物同样是纯静态文件推送到任意静态托管平台即可配合 CI 实现提交即发布。构建产物目录public/即完整站点验证无误后切流量、下线旧站迁移完成 四、迁移前后对照表能力Docbase旧Gatsby新文档来源Markdown 文件 / GitHub / HTTPMarkdown / MDX 任意数据源版本管理docbase.json 手工声明frontmatter 查询过滤导航菜单两级侧边栏可定制 React 组件全文搜索离线搜索索引生态插件 / 搜索服务技术栈jQuery AngularJS GruntReact GraphQL 现代工具链维护状态⛔ 已停止维护✅ 活跃生态五、写在最后告别不是终点Docbase 从 2015 年的 v0.0.1 走到 v0.3.0package.json中版本已迭代至 1.0.3用简洁的 JSON 配置解决了Markdown 文档站的第一代问题。它的 MIT 许可证见LICENSE意味着你随时可以阅读scripts/docbase.js等源码把它当成一个经典的单页文档引擎案例来学习。对于正在运营文档站的你今天就可以开始第 1 步——你的 Markdown 文件不会浪费它们会在 Gatsby 里继续发光。【免费下载链接】DocbaseTurn .md docs into beautiful sites项目地址: https://gitcode.com/gh_mirrors/do/Docbase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
