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

Docbase 文档目录结构完全指南版本/文件夹/Markdown 三级组织法与 index 页写法【免费下载链接】DocbaseTurn .md docs into beautiful sites项目地址: https://gitcode.com/gh_mirrors/do/DocbaseDocbase 是一个把 Markdown 文件变成漂亮文档站点的开源工具自带多版本管理、自动导航菜单和离线搜索。本文带你完全掌握 Docbase 文档目录结构版本 → 文件夹 → Markdown 文件的三级组织法以及如何通过docbase.json声明目录树、让每个文件夹自动拥有 index 目录页。一、Docbase 是什么一个目录即菜单的文档站点工具传统写文档的痛点Markdown 文件躺在仓库里读者得自己翻目录版本一多v1 和 v2 的内容混在一起根本分不清。Docbase 的解决思路很直接目录即菜单docs 目录下的层级会自动渲染成顶部导航和侧边栏版本即入口每个版本如 v1.0、v2.0独立成站顶部可一键切换文件即页面每个.md文件渲染为一个独立页面支持代码高亮文档来源支持三种方式通过配置中的method字段指定file本地目录、githubGitHub 仓库、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 的映射页面地址格式为#/{版本}/{文件夹}/{文件}与目录一一对应页面地址对应文件#/v1.0/folder1folder1 的 index 目录页自动生成#/v1.0/folder1/file1docs/v1.0/folder1/file1.md#/v2.0/folder2/file2docs/v2.0/folder2/file2.md三、在 docbase.json 中声明你的目录树目录结构确定后需要在配置文件中声明。项目根目录提供两种等价写法docbase.json —— JSON 格式适合纯配置docbase-config.js —— 以docbaseConfig变量定义index.html会加载它关键配置项一览字段作用示例值method文档来源方式file/github/genericfile.path本地文档根目录docsversions版本 → 文件夹 → 文件的目录树见下方示例indexHtml站点入口落地页模板html/main.htmlflatdocHtml文档阅读页模板html/flatdoc.htmllabel 与 name 的分工versions中每个节点都有两个字段这是最容易搞混的地方name必须和实际目录名/文件名一致不带扩展名它决定 URLlabel显示在导航菜单上的文字可以写成人类友好的短语versions: { v1.0: [ { label: Folder 1, name: folder1, files: [ { label: File 1, name: file1 } ] } ] }新增一个文档的步骤清单✅ 在docs/v1.0/下新建文件夹放入.md文件✅ 在配置文件的versions对应版本中追加一个文件夹节点✅ 为每个文件写label和name✅ 重新构建后刷新页面导航菜单自动出现新条目四、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。五、目录结构常见坑与自检清单⚠️ 新手最常踩的几个坑现象原因解决方法页面 404配置里的name和实际文件名不一致核对文件名name不带.md后缀新文章没出现在菜单只在 docs 下加了文件没改配置在versions对应节点补上文件声明版本切换后内容错乱两个版本目录结构不一致且未分别声明每个版本单独维护完整的文件夹/文件列表中文菜单显示乱码页面模板未声明 UTF-8入口 HTML 中确认charsetutf-8 发布前自检清单目录严格保持版本 → 文件夹 → 文件三层没有多余嵌套配置中每个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.jsindex 注入、路由、搜索构建入口GruntFile.js掌握了三级组织 配置声明 自动 index 页这三点你就能用 Docbase 快速搭出一个带版本切换、导航菜单和离线搜索的专业文档站点。【免费下载链接】DocbaseTurn .md docs into beautiful sites项目地址: https://gitcode.com/gh_mirrors/do/Docbase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考