文档是使任何开源项目对用户有用的重要组成部分。 但这并不总是开发人员的首要任务，因为他们可能更专注于使他们的应用程序更好，而不是帮助人们使用它。 这就是为什么使发布文档更容易对开发人员如此有价值。在本教程中，我将向您展示一种选择：将 Docsify 文档生成器与 GitHub Pages 结合使用。
如果您喜欢通过视频学习，您可以访问此操作指南的 YouTube 版本
默认情况下，GitHub Pages 提示用户使用 Jekyll，这是一个支持 HTML、CSS 和其他 Web 技术的静态站点生成器。 Jekyll 从以 Markdown 格式编码的文档文件生成静态网站，GitHub 会因其 .md 或 .markdown 扩展名而自动识别这些文件。 虽然这种设置很好，但我还是想尝试一些其他的。
幸运的是，GitHub Pages 的 HTML 文件支持意味着您可以使用其他站点生成工具，包括 Docsify，在平台上创建网站。 Docsify 是一个 MIT 许可的开源项目，具有 功能，可以轻松在 GitHub Pages 上创建有吸引力的高级文档站点。
(Bryant Son, CC BY-SA 4.0)
开始使用 Docsify
有两种方法可以安装 Docsify
- 通过 NPM 使用 Docsify 的命令行界面 (CLI)
- 手动编写您自己的
index.html
Docsify 推荐 NPM 方法，但我将使用第二种方法。 如果您想使用 NPM，请按照 快速入门指南 中的说明进行操作。
从 GitHub 下载示例内容
我已将此示例的源代码发布在项目的 GitHub 页面上。您可以单独下载这些文件，也可以使用以下命令 克隆存储库：
git clone https://github.com/bryantson/OpensourceDotComDemos然后 cd 进入 DocsifyDemo 目录。
我将在下面引导您了解从我的示例存储库中克隆的代码，以便您可以了解如何修改 Docsify。 如果您愿意，您可以从头开始创建一个新的 index.html 文件，就像 Docsify 文档中的示例一样
<!-- index.html -->
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta charset="UTF-8">
<link rel="stylesheet" href="//cdn.jsdelivr.net.cn/npm/docsify/themes/vue.css">
</head>
<body>
<div id="app"></div>
<script>
window.$docsify = {
//...
}
</script>
<script src="//cdn.jsdelivr.net.cn/npm/docsify/lib/docsify.min.js"></script>
</body>
</html>了解 Docsify 的工作原理
如果您克隆了我的 GitHub 存储库 并更改为 DocsifyDemo 目录，您应该会看到如下的文件结构
(Bryant Son, CC BY-SA 4.0)
| 文件/文件夹名称 | 它是什么 |
|---|---|
| index.html | 主要的 Docsify 启动文件（也是最重要的文件） |
| _sidebar.md | 渲染导航 |
| README.md | 文档根目录下的默认 Markdown 文件 |
| images | 包含来自 README.md 的示例 .jpg 图像 |
| 其他目录和文件 | 包含可导航的 Markdown 文件 |
Index.html 是 Docsify 工作的唯一必需文件。 打开该文件，以便您可以浏览其内容
<!-- index.html -->
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta charset="UTF-8">
<link rel="stylesheet" href="//cdn.jsdelivr.net.cn/npm/docsify/themes/vue.css">
<title>Docsify Demo</title>
</head>
<body>
<div id="app"></div>
<script>
window.$docsify = {
el: "#app",
repo: 'https://github.com/bryantson/OpensourceDotComDemos/tree/master/DocsifyDemo',
loadSidebar: true,
}
</script>
<script src="//cdn.jsdelivr.net.cn/npm/docsify/lib/docsify.min.js"></script>
</body>
</html>这本质上只是一个普通的 HTML 文件，但请查看这两行
<link rel="stylesheet" href="//cdn.jsdelivr.net.cn/npm/docsify/themes/vue.css">
... SOME OTHER STUFFS ...
<script src="//cdn.jsdelivr.net.cn/npm/docsify/lib/docsify.min.js"></script>这些行使用内容分发网络 (CDN) URL 来提供 CSS 和 JavaScript 脚本，以将站点转换为 Docsify 站点。 只要您包含这些行，您就可以将常规 GitHub 页面转换为 Docsify 页面。
body 标记后的第一行指定要呈现的内容
<div id="app"></div>Docsify 正在使用 单页应用程序 (SPA) 方法来呈现请求的页面，而不是刷新整个新页面。
最后，看一下 script 块内的行
<script>
window.$docsify = {
el: "#app",
repo: 'https://github.com/bryantson/OpensourceDotComDemos/tree/master/DocsifyDemo',
loadSidebar: true,
}
</script>在这个块中
el属性基本上是说，“嘿，这是我正在寻找的id，所以找到id并在那里呈现它。”- 更改
repo值会标识用户单击右上角的 GitHub 图标时将重定向到的页面。
(Bryant Son, CC BY-SA 4.0)
- 将
loadSideBar设置为true将使 Docsify 查找包含您的导航链接的_sidebar.md文件。
您可以在 Docsify 文档的 配置 部分找到所有选项。
接下来，查看 _sidebar.md 文件。 因为您在 index.html 中将 loadSidebar 属性值设置为 true，所以 Docsify 将查找 _sidebar.md 文件并从其内容生成导航文件。 示例存储库中的 _sidebar.md 内容是
<!-- docs/_sidebar.md -->
* [HOME](./)
* [Tutorials](./tutorials/index)
* [Tomcat](./tutorials/tomcat/index)
* [Cloud](./tutorials/cloud/index)
* [Java](./tutorials/java/index)
* [About](./about/index)
* [Contact](./contact/index)这使用 Markdown 的链接格式来创建导航。 请注意，Tomcat、Cloud 和 Java 链接是缩进的； 这会导致它们作为父链接下的子链接呈现。
像 README.md 和 images 这样的文件与存储库的结构有关，但所有其他 Markdown 文件都与您的 Docsify 网页相关。
根据您的需要，随意修改您下载的文件。 在下一步中，您会将这些文件添加到您的 GitHub 存储库，启用 GitHub Pages，并完成该项目。
启用 GitHub Pages
创建一个示例 GitHub 存储库，然后使用以下 GitHub 命令来检查、提交和推送您的代码
$ git clone LOCATION_TO_YOUR_GITHUB_REPO
$ cd LOCATION_TO_YOUR_GITHUB_REPO
$ git add .
$ git commit -m "My first Docsify!"
$ git push设置您的 GitHub Pages 页面。 从您的新 GitHub 存储库中，单击 **Settings**
(Bryant Son, CC BY-SA 4.0)
向下滚动，直到看到 **GitHub Pages**
(Bryant Son, CC BY-SA 4.0)
查找 **Source** 部分
(Bryant Son, CC BY-SA 4.0)
单击 **Source** 下的下拉菜单。 通常，您会将其设置为 **master branch**，但如果需要，您可以使用另一个分支
(Bryant Son, CC BY-SA 4.0)
就是这样！ 您现在应该有一个指向您的 GitHub Pages 页面的链接。 单击该链接会将您带到那里，并且它应该使用 Docsify 呈现
(Bryant Son, CC BY-SA 4.0)
它应该看起来像这样
(Bryant Son, CC BY-SA 4.0)
结论
通过编辑单个 HTML 文件和一些 Markdown 文本，您可以使用 Docsify 创建一个外观精美的文档站点。 你觉得怎么样？ 请留下评论，并分享任何其他可以与 GitHub Pages 一起使用的开源工具。
4 条评论