使用 Github Pages 发布你的项目文档

 你可能比较熟悉如何用 Github Pages 来分享你的工做，又或许你看过一堂教你创建你的第一个 Github Pages 网站的教程。近期 Github Pages 的改进使得从不一样的数据源来发布您的网站更加的方便，其中的来源之一就是你的仓库的 /docs 目录。

文档的质量是一个软件项目健康发展的标志。对于开源项目来讲，维护一个可靠而不出错的知识库、详细说明全部的细节是相当重要的。精心策划的文档可让增长项目的亲切感，提供一步步的指导并促进各类方式的合做能够推进开源软件开发的协做进程。

在 Web 上托管你的文档是一个消耗时间的挑战，并且对于它的发布和维护也没有省事的办法，然而这是并不是不可避免的。面对多种不一样的发布工具，又是 FTP 服务器，又是数据库，文件以各类不一样的方式存放在不一样的位置下，而这些都须要你手动来调整。须要说明的是，传统的 Web 发布方式提供了无与伦比的灵活性和性能，可是在许多状况下，这是以牺牲简单易用为代价的。

看成为文档使用时，麻烦更少的方式显然更容易去维护。

GitHub Pages 能够以指定的方式为你的项目建立网站，这使得它自然地适合发布和维护文档。由于 Github Pages 支持 Jekyll，因此你可使用纯文本或 Markdown 来书写你的文档，从而下降你维护的成本、减小维护时的障碍。Jekyll 还支持许多有用的工具好比变量、模板、以及自动代码高亮等等，它会给你更多的灵活性而不会增长复杂性，这些你在一些笨重的平台是见不到的。

最重要的是，在 Github 上使用 GitHub Pages 意味着你的文档和代码可使用诸如 Issues 和 Pull Requests 来确保它获得应有的高水平维护，并且由于 GitHub Pages 容许您发布代码库主分支上的 /docs 目录，这样您就能够在同一分支同时维护你的代码库及其文档。

如今开始！

发布你的第一个文档页面只须要短短几分钟。

1. 在你的仓库的主分支里建立一个 /docs/index.md 文件。
2. 把你的内容以 Jekyll 格式添加进去，并提交你的修改。
   
3. 查看你的仓库的设置分支而后选择主分支 /docs 目录，将其设置为 GitHub Pages 的源 ，点击保存，你就搞定了。

GitHub Pages 将会从你的 /docs 目录中读取内容，转换 index.md 为 HTML。而后把它发布到你的 GitHub Pages 的 URL 上。

这样将会建立并输出一个最基础的 HTML ，并且你可使用 Jekyll 的自定义模板、CSS 和其余特性。若是想要看全部的可能，你能够看看 GitHub Pages Showcase。

本文转载地址：https://www.linuxprobe.com/linux-help-with-cheat.html