Docbase 的 3 种 Markdown 数据源GitHub、本地文件、HTTP 服务器加载文档全对比【免费下载链接】DocbaseTurn .md docs into beautiful sites项目地址: https://gitcode.com/gh_mirrors/do/DocbaseDocbase 是一款把.md文件变成带版本导航的漂亮文档站的工具。它最实用的能力之一就是支持3 种 Markdown 数据源从GitHub仓库拉取、读取本地文件或通过HTTP 服务器在线加载。无论你是写开源项目手册还是搭内部知识库搞清楚这三种方式的区别都能帮你一步选对配置。一分钟看懂3 种数据源怎么选Docbase 用配置文件里的method字段来指定数据源可选值就三个file、github、generic。先看懂下面这张对比表你就有了全局观。数据源method值目录映射从哪来.md内容从哪来适用场景本地文件file本地map.json本地docs/目录离线开发、私有文档、本地预览GitHubgithubGitHub API 自动扫描仓库 raw 源开源项目、随仓库自动更新HTTP 服务器generic本地map.json你指定的baseurl文档已部署到任意静态服务器 默认配置见 docbase.json其中method默认为file。也可以写成 JS 形式参考docbase-config.js和sample-docbase-config.js。数据源一本地文件file这是最贴近新手友好的方式。Docbase 会读取本地的一份map.json作为目录清单再从file.path指定的目录默认docs里加载对应的.md文件。它适合谁想在本地快速预览文档效果文档内容是私有的不方便放到公开仓库不想依赖任何外部网络服务上手要点确认map.json里的版本、目录、文件三层结构和实际文件一致file.path指向你的.md所在目录例如docs每个目录会自动补一个index入口页项目自带的示例文档就放在docs/下按v1.0、v2.0两个版本、folder1、folder2两级目录组织正好是本地模式的标准结构可以照着搭。数据源二GitHubgithub这是开源项目最常用的一条路。Docbase 会调用 GitHub API 扫描仓库里所有.md文件自动构建目录再从 raw 源加载正文完全不用你手写目录清单。它适合谁文档和代码放在同一个仓库希望改完即更新想让文档站展示提交记录与贡献者头像上手要点必填github.user和github.repo缺一会直接报错可在spec/DocbaseSpec.js里看到对应的校验用例branch指定分支默认gh-pagespath指定文档子目录若 API 配额超限Docbase 会回退到读取本地map.json保证站点不白屏小技巧把配置里的editGithubBtn设为true每个文档页底部就会出现去 GitHub 编辑本页的按钮方便社区纠错。数据源三HTTP 服务器generic当你的.md文件已经部署在某个静态服务器或对象存储上时就用generic模式。它的特点是目录用本地map.json正文走远程——从generic.baseurl加generic.path拼出每个文件的在线地址。它适合谁文档托管在 CDN、Nginx 静态目录或任何可访问的http(s)://地址不想暴露仓库结构只想发布纯静态文档上手要点在配置里填好generic.baseurl如你的域名或静态目录地址配好generic.path作为路径前缀同样需要一份结构正确的map.json来驱动左侧目录示例配置可直接参考spec/json/docbase-sample-generic.json它把method设为generic并保留了完整的版本目录结构。三种方式到底怎么选离线 / 私有 / 本地预览→ 选file最省心、零依赖开源 / 想随仓库自动更新→ 选github还能带贡献者和编辑入口已部署到静态服务器→ 选generic目录本地、正文在线一句话总结先看文档住在哪再决定用哪个method。三种模式共用同一套版本目录结构切换时只需改method和对应字段迁移成本很低。想深入看这几处数据源调度与加载逻辑scripts/docbase.jsDocbase.methods、Docbase.github、Docbase.file、Docbase.generic默认配置模板docbase.json、docbase-config.js各模式样例配置spec/json/docbase-sample-github.json、spec/json/docbase-sample-generic.json配置校验测试spec/DocbaseSpec.js照着这份对比你就能在 GitHub、本地文件与 HTTP 服务器之间做出最合适的选择了。【免费下载链接】DocbaseTurn .md docs into beautiful sites项目地址: https://gitcode.com/gh_mirrors/do/Docbase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考