企业官网建设流程全解析

快速上手 Docbase 构建与部署：Grunt 单文件打包到 GitHub Pages 发布的 5 步指南

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

Docbase是一款轻量灵活的单页文档引擎，能把你的Markdown（.md）文档一键转换成带版本切换、侧边菜单和离线搜索的精美静态文档站。它支持从本地目录、GitHub 仓库或任意 HTTP 服务器读取文档，并可将文档站发布到 GitHub Pages 或本地静态托管。本文将带你走一遍Docbase 构建与部署的完整流程：从Grunt 单文件打包到GitHub Pages 发布，只需 5 步 🚀

第 1 步：安装依赖，准备构建环境

Docbase 的前端依赖（如 Flatdoc 主题、jQuery、Angular、Bootstrap）通过 Bower 管理，构建工具链则由 Grunt 驱动。在项目根目录执行：

npm install bower install

• npm install安装 Grunt 及 GruntFile.js 中声明的各类构建插件
• bower install拉取 bower.json 中声明的前端库

💡 环境要求：Node.js >= 0.8（见 package.json 中的 engines 字段）。

第 2 步：配置 docbase-config.js 定义文档版本结构

打开 docbase-config.js（或等价的 docbase.json），重点配置三个字段：

项目的示例文档就放在docs/v1.0/和docs/v2.0/下，与配置中的versions一一对应。如果你的文档托管在 GitHub，可改为method: "github"并填写github.user、github.repo、branch等字段，配置校验规则可参考 spec/DocbaseSpec.js 中的用例（缺少user或repo时会直接抛错）。

第 3 步：运行 Grunt 完成单文件打包

核心打包逻辑全部集中在 GruntFile.js 中。执行默认任务：

grunt

它会依次完成5 个构建环节：

1. jshint— 代码风格检查
2. jasmine— 运行 spec/DocbaseSpec.js 单元测试
3. concat— 将scripts/**/*.js合并为dist/js/main.js
4. uglify— 压缩出dist/js/main.min.js，并通过unicfile目标把所有第三方库与业务脚本打包成单一文件dist/js/main.unique.js
5. cssmin— 将styles/main.css、styles/docs.css压缩为dist/css/main.min.css

这个main.unique.js就是Grunt 单文件打包的精髓：部署时无需再关心一堆 JS 依赖，一个文件搞定全部逻辑（含核心引擎 scripts/docbase.js）。

第 4 步：本地预览，验证文档站点

打包完成后，用任意静态服务器（如npx http-server）启动项目根目录，打开 index.html 即可预览。页面只依赖两个脚本：

• ./docbase-config.js— 你在第 2 步写的文档配置
• /dist/main.unique.js— 上一步打包出的单文件

看到左侧版本切换菜单（v1.0 / v2.0）和渲染后的 Markdown 内容，说明构建成功 ✅。另外 search-index.json 是离线搜索索引，由构建流程生成，让搜索功能无需联网也能工作。

第 5 步：发布到 GitHub Pages

Docbase 生成的站点是纯静态文件，发布到 GitHub Pages 非常简单：

1. 将index.html、dist/、styles/、html/、images/及docbase-config.js复制到站点的gh-pages分支
2. 在仓库 Settings 中开启 Pages 并指定gh-pages分支
3. 等待推送完成，通过https://<用户名>.github.io/<仓库名>访问你的文档站

项目自带的 sample-index.html 展示了以 Bower 依赖方式引用 Docbase 的写法，可作为你线上页面结构参考。README 中也提到可通过 CI（Travis）在每次提交时自动完成打包与发布，实现文档站点的持续部署。

📋 发布前快速核对清单

• ✅grunt构建无 jshint 告警、jasmine 测试全部通过
• ✅docbase-config.js中versions与docs/目录结构一致
• ✅ 页面引用的是打包后的dist/main.unique.js而非源码目录
• ✅ 本地静态服务器预览导航、版本切换、搜索均正常
• ✅ 静态文件已推送至gh-pages分支

相关文件速查

按以上 5 步走下来，你就能把一摞 Markdown 文件变成专业美观、支持多版本的文档站，并稳定地发布在 GitHub Pages 上 🎉

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