企业官网建设流程全解析

Docbase 文档目录结构完全指南：版本/文件夹/Markdown 三级组织法与 index 页写法

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

Docbase 是一个把 Markdown 文件变成漂亮文档站点的开源工具，自带多版本管理、自动导航菜单和离线搜索。本文带你完全掌握 Docbase 文档目录结构：版本 → 文件夹 → Markdown 文件的三级组织法，以及如何通过docbase.json声明目录树、让每个文件夹自动拥有 index 目录页。

一、Docbase 是什么：一个"目录即菜单"的文档站点工具

传统写文档的痛点：Markdown 文件躺在仓库里，读者得自己翻目录；版本一多，v1 和 v2 的内容混在一起，根本分不清。

Docbase 的解决思路很直接：

• 📂目录即菜单：docs 目录下的层级会自动渲染成顶部导航和侧边栏
• 🔖版本即入口：每个版本（如 v1.0、v2.0）独立成站，顶部可一键切换
• 📄文件即页面：每个.md文件渲染为一个独立页面，支持代码高亮

文档来源支持三种方式，通过配置中的method字段指定：file（本地目录）、github（GitHub 仓库）、generic（任意 HTTP 服务器）。新手推荐从file开始。

二、三级组织法：版本 / 文件夹 / Markdown 文件

这是 Docbase 文档目录结构的核心。以本项目自带的示例目录为例：

docs/ ├── v1.0/ │ ├── folder1/ │ │ └── file1.md │ └── folder2/ │ ├── file1.md │ └── file2.md └── v2.0/ ├── folder1/ │ └── file1.md └── folder2/ ├── file1.md └── file2.md

第一级：版本目录（v1.0、v2.0）

• 版本名就是目录名，通常写成v1.0、v2.0这种带版本号的格式
• 不同版本的内容完全隔离，读者在页面右上角即可切换版本
• 新版本上线时，不要删旧版本目录——存量用户可能还停留在旧文档上

第二级：功能文件夹（folder1、folder2）

• 按主题划分，如install/（安装）、api/（接口）、faq/（常见问题）
• 文件夹会自动生成一个 index 目录页（下文详述），读者点进文件夹就能浏览该主题下所有文章
• 建议单版本内控制在 5~8 个文件夹，导航菜单更易读

第三级：Markdown 页面（file1.md、file2.md）

• 每个.md文件渲染为一个页面，支持标准 Markdown 语法与代码块
• 文件名只决定 URL，显示给读者的文字由配置文件中的label控制，所以文件名可以放心用短横线风格（如quick-start.md）

目录结构与 URL 的映射

页面地址格式为#/{版本}/{文件夹}/{文件}，与目录一一对应：

三、在 docbase.json 中声明你的目录树

目录结构确定后，需要在配置文件中声明。项目根目录提供两种等价写法：

• docbase.json —— JSON 格式，适合纯配置
• docbase-config.js —— 以docbaseConfig变量定义，index.html会加载它

关键配置项一览：

label 与 name 的分工

versions中每个节点都有两个字段，这是最容易搞混的地方：

• name：必须和实际目录名/文件名一致（不带扩展名），它决定 URL
• label：显示在导航菜单上的文字，可以写成人类友好的短语

"versions": { "v1.0": [ { "label": "Folder 1", "name": "folder1", "files": [ { "label": "File 1", "name": "file1" } ] } ] }

新增一个文档的步骤清单：

1. ✅ 在docs/v1.0/下新建文件夹，放入.md文件
2. ✅ 在配置文件的versions对应版本中追加一个文件夹节点
3. ✅ 为每个文件写label和name
4. ✅ 重新构建后刷新页面，导航菜单自动出现新条目

四、index 页写法：让每个文件夹自动拥有目录页

很多新手不知道：Docbase 的每个文件夹都会自动生成一个 index 目录页，无需手写任何页面。

自动生成的文件夹 index 页

核心逻辑在 scripts/docbase.js 的Docbase._index函数中：构建时它会向每个文件夹的文件列表里自动注入一个index条目。效果是：

• 访问#/v1.0/folder1时，显示该文件夹的目录页，标题为"文件夹名 (N files)"
• 页面内两栏列出该文件夹下所有文章的链接
• 进入具体文章后，右侧侧边栏显示 "Other pages in" 同目录文章列表

模板实现见 html/flatdoc.html 中的index-container部分。

站点入口页（Landing Page）

站点根路径/显示的不是文件夹 index，而是由indexHtml指定的入口模板（默认html/main.html），通常用于展示项目简介和几个核心入口链接。页面骨架由 index.html 提供，它负责加载配置与 Docbase 主程序。

导航菜单与版本切换

顶部菜单由 html/navbar.html 渲染：遍历当前版本的文件夹生成下拉菜单，右侧提供版本切换下拉框和搜索框（离线搜索索引为search-index.json）。

五、目录结构常见坑与自检清单

⚠️ 新手最常踩的几个坑：

📋 发布前自检清单：

• 目录严格保持"版本 → 文件夹 → 文件"三层，没有多余嵌套
• 配置中每个name都能在实际目录中找到对应文件
• 每个文件夹的label对读者有明确指向（如"快速上手"而非"folder1"）
• 旧版本目录保留，且versions中完整声明

六、相关文件速查

• 示例文档目录：docs/v1.0/、docs/v2.0/
• 配置示例：docbase.json、docbase-config.js、sample-docbase-config.js
• 更多配置样例：spec/json/docbase-sample-generic.json、spec/json/docbase-sample-github.json
• 页面模板：html/main.html（入口页）、html/flatdoc.html（阅读页与 index 目录页）、html/navbar.html（导航）
• 核心逻辑：scripts/docbase.js（index 注入、路由、搜索）
• 构建入口：GruntFile.js

掌握了"三级组织 + 配置声明 + 自动 index 页"这三点，你就能用 Docbase 快速搭出一个带版本切换、导航菜单和离线搜索的专业文档站点。

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