企业官网建设流程全解析

如何用 Docbase 做多版本文档管理？versions 配置与版本一键切换完整教程

【免费下载链接】DocbaseTurn .md docs into beautiful sites项目地址: https://gitcode.com/gh_mirrors/do/Docbase

Docbase 是一个把 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）：

两个能省事的细节：

1. index 会自动补上：核心引擎（scripts/docbase.jsL128-L146 的Docbase._index函数）会给每个文件夹的 files 数组自动追加一个index项，所以只要文件夹里有 index.md，落地页就能直接访问，无需额外声明。
2. github 模式下 label 可省略：如果文档托管在 GitHub 仓库（method: "github"），引擎会自动遍历仓库树生成目录映射（scripts/docbase.jsL819-L855），versions 配置只用来定制显示名称，配置量大大减少。

第三步：导航栏一键切换版本，原理与效果 ✨

顶部导航由html/navbar.html渲染，其中 L36-L49 内置了一个版本下拉菜单：

• 下拉项根据 versions 配置的版本名自动生成
• 点击某个版本后，页面的当前版本立即更新，导航菜单、文档内容、翻页链接随之整体切换
• 切换后落在该版本的第一页（配置中第一个文件夹的第一个文件，逻辑见scripts/docbase.jsL305-L310 的getVersionLink）

URL 与版本也是绑定的：/:version/:folder/:file等路由统一在scripts/docbase.js（L274-L295）中声明。这意味着把 v1.0 的页面链接分享给别人，对方打开的永远还是 v1.0，跨版本不会串页。

进阶技巧：设置默认打开的版本 🎯

默认情况下，首页会展示 versions 中的第一个版本。如果希望站点默认进入 v2.0，在配置中加一个字段即可：

{ "default_version": "v2.0" }

首页逻辑（scripts/docbase.jsL586）会优先读取default_version，未设置时才回退到第一个版本。这对“官网展示最新版、老版本仍可查阅”的场景非常实用。

三种文档加载方式，任选其一 🔧

Docbase 通过method字段支持三种数据来源（见scripts/docbase.jsL28），versions 的写法完全一致：

常见坑位速查 ⚠️

1. name 与实际文件名不一致：name必须与文件夹名/文件名（不含 .md）完全一致，差一个字符就会打不开页面。
2. 版本 key 用了空格或特殊字符：URL 路径由 key 直接生成，建议用v2.0这种英文写法；label则可以放心用中文。
3. JSON 语法错误：配置文件无效时加载会直接报错，建议对照官方示例spec/json/docbase-sample.json检查结构。
4. 文件夹缺 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