如何用 Docbase 做多版本文档管理versions 配置与版本一键切换完整教程【免费下载链接】DocbaseTurn .md docs into beautiful sites项目地址: https://gitcode.com/gh_mirrors/do/DocbaseDocbase 是一个把 Markdown.md文档转换成漂亮文档站点的开源工具内置多版本文档管理能力。本文通过完整示例讲清楚 Docbase 的 versions 配置写法、目录组织规范以及导航栏版本一键切换的实现原理帮你一次配置、长期省心。为什么需要多版本文档管理 开源项目常常同时维护多个大版本v1.0 的用户和 v2.0 的用户需要看到各自对应的文档。自己拼静态页面时常见痛点有多套文档来回手动切换容易贴错页面新旧版本混在一起新手无所适从升级新版文档时误伤旧版内容Docbase 的核心思路是每个版本一个独立 URL 路径如#/v1.0/guide/intro与#/v2.0/guide/intro再配合顶部导航的版本下拉菜单用户点击即可一键切换版本互不干扰。5 分钟快速上手克隆仓库并本地运行 在本地克隆项目或作为学习参考git clone https://gitcode.com/gh_mirrors/do/Docbase官方提供了 Yeoman 生成器三条命令即可在本地跑起一个文档站点npm install -g yo npm install -g generator-docbase yo docbase运行成功后会在http://127.0.0.1:1234看到渲染好的文档站点。第一步按「版本/文件夹/文件」组织文档目录 ️Docbase 要求文档目录是三级结构版本 / 文件夹 / 文件。项目自带的示例文档正是这样组织的docs/ ├── v1.0/ │ ├── folder1/file1.md │ └── folder2/file1.md、file2.md └── v2.0/ ├── folder1/file1.md └── folder2/file1.md、file2.md对应项目中的docs/v1.0/与docs/v2.0/两个目录。要点第一级是版本名取什么由你定v1.0、v2.0、2024.1都可以第二级是文档分组会渲染成顶部导航菜单第三级是具体的 .md 文件文件夹里放一个index.md它就会自动成为该文件夹的落地页第二步versions 配置详解逐字段说明 ⚙️打开根目录的docbase.json或docbase-config.js在versions字段里声明版本结构。下面是最小可用示例{ method: file, file: { path: docs }, versions: { v1.0: [ { label: 快速上手, name: folder1, files: [ { label: 入门指南, name: file1 } ] }, { label: 进阶, name: folder2, files: [ { label: File 1, name: file1 }, { label: File 2, name: file2 } ] } ], v2.0: [ ……与 v1.0 结构相同…… ] } }字段速查表官方完整示例见docbase.json的 L17-L70字段含义示例外层 key版本名同时成为 URL 路径的一部分v1.0、v2.0label顶部导航里的显示文案可随意起快速上手name真实文件夹名/文件名不带 .mdfolder1、file1files该文件夹下的 .md 文件按展示顺序排列—两个能省事的细节index 会自动补上核心引擎scripts/docbase.jsL128-L146 的Docbase._index函数会给每个文件夹的 files 数组自动追加一个index项所以只要文件夹里有 index.md落地页就能直接访问无需额外声明。github 模式下 label 可省略如果文档托管在 GitHub 仓库method: github引擎会自动遍历仓库树生成目录映射scripts/docbase.jsL819-L855versions 配置只用来定制显示名称配置量大大减少。第三步导航栏一键切换版本原理与效果 ✨顶部导航由html/navbar.html渲染其中 L36-L49 内置了一个版本下拉菜单下拉项根据 versions 配置的版本名自动生成点击某个版本后页面的当前版本立即更新导航菜单、文档内容、翻页链接随之整体切换切换后落在该版本的第一页配置中第一个文件夹的第一个文件逻辑见scripts/docbase.jsL305-L310 的getVersionLinkURL 与版本也是绑定的/:version/:folder/:file等路由统一在scripts/docbase.jsL274-L295中声明。这意味着把 v1.0 的页面链接分享给别人对方打开的永远还是 v1.0跨版本不会串页。进阶技巧设置默认打开的版本 默认情况下首页会展示 versions 中的第一个版本。如果希望站点默认进入 v2.0在配置中加一个字段即可{ default_version: v2.0 }首页逻辑scripts/docbase.jsL586会优先读取default_version未设置时才回退到第一个版本。这对“官网展示最新版、老版本仍可查阅”的场景非常实用。三种文档加载方式任选其一 Docbase 通过method字段支持三种数据来源见scripts/docbase.jsL28versions 的写法完全一致method说明适合场景file读取本地docs/目录下的 Markdown本地开发、静态站点部署github从 GitHub 仓库自动映射文档附带贡献者头像和“编辑此页”按钮文档与代码同仓库维护generic从任意 http 服务器拉取托管在内网服务器常见坑位速查 ⚠️name 与实际文件名不一致name必须与文件夹名/文件名不含 .md完全一致差一个字符就会打不开页面。版本 key 用了空格或特殊字符URL 路径由 key 直接生成建议用v2.0这种英文写法label则可以放心用中文。JSON 语法错误配置文件无效时加载会直接报错建议对照官方示例spec/json/docbase-sample.json检查结构。文件夹缺 index.md访问文件夹首页会没有内容记得每个分组都补一个 index 文件。小结 ✅用 Docbase 做多版本文档管理只需三步按「版本/文件夹/文件」组织目录 → 在 versions 中声明菜单结构 → 导航栏自动获得一键切换能力再配合default_version指定默认版本即可。想深入源码重点关注这几个文件配置模板docbase.json、docbase-config.js核心引擎scripts/docbase.js导航与版本切换html/navbar.html单元测试spec/DocbaseSpec.js小提示项目 README 中说明 Docbase 已不再积极维护官方建议新项目使用 Gatsby本文教程适用于已有 Docbase 站点及存量文档体系其多版本机制至今依然完整可用。【免费下载链接】DocbaseTurn .md docs into beautiful sites项目地址: https://gitcode.com/gh_mirrors/do/Docbase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考