提供书写良好的文档,可以帮助人们理解并很好地使用你的项目,而且人们还能够很容易地参与你的项目并作出贡献,但这仍不够。基于文档服务的底层系统能够使任何人——包括你或你的团队写文档更轻松。
对于文档的编写,最大的难点不是如何配置工具,或者要弄清楚怎么部署更新,而在于如何斟词酌句。GitHub文档制作团队的成员有着丰富的工作背景,包括使用原生的基于XML的写作工具,以及复杂的CMS系统。但我们并不想使用那些工具,因此我们花费了大量时间和精力来配置我们自己的文档制作流程和工作计划。
以前我们也谈论过怎么使用GitHub构建GitHub;如下就是我们怎样使用 GitHub Pages 每月向数百万读者提供 我们的GitHub帮助文档。
我们以前的流程几个月前,我们把帮助系统的站点从自建的Rails程序迁移到了 Github Pages 上的Jekyll。之前我们的帮助系统需要两个相互独立的项目仓库:
负责运维网站、管理网站资源,以及实现文档搜索的 Rails 应用程序
由一大堆 Markdown 文件组成的网站具体内容
我们的 Rails 应用程序托管在一个第三方平台上。随着代码的不断更新升级,我们将它部署在了 Hubotand Chatops ,这些都是我们在维护 Github 主站的闲暇之余完成的。
我们正常的撰写流程可能是这个样子的:
下面是一个简单的示例,@neveretand@bernars给我们展示了一下我们正常的工作流程:
使用pull requests进行工作很有意思,因为它正好和我们团队使用的 Github工作流程是一致的。并且Markdown 的语法能让我们快速高效地表达出新特性的独到之处,所以我们写文档时,对它情有独钟。
然而,我们的 Rails 程序维护起来相当麻烦:
由于我们的主机是外部托管,所以我们需要工程,运维和安全团队的专业人员实时监控站点运行状况,并能及时处理突发事件。
我们的文档团队并不能方便的预览内容的变化。虽然我们使用 Markdown 编写内容,可以实时预览,但是我们仍然需要配置一个本地的 Rails 应用服务去运行脚本将内容导入到数据库中然后观察其在网站上的最终效果。
虽然我们不断的调整 Rails 服务器设置,而用户发起请求后响应速度依然缓慢。这是因为 HTML 页面是动态生成的,需要对数据库进行频繁访问,即便运用更为强大的缓存策略,依然收效甚微。
我们意识到,其实我们可以做得更好。
我们的新流程当 Jekyll 2.0 发布的时候,我们意识到是时候使用静态网站了!特别是 Collections文档类型这个新特性使得定义自己的文件结构成为可能。不仅如此,Jekyll 2.0 还增加了 Sass 和 CoffeeScript 的支持,让前端代码的编写更简单。
开源的好处在于它是开放的。我们迁移到 Jekyll 后,我们也向 Jekyll项目发起了很多pull requests,贡献代码,使得它能更好的服务 Github Pages 的广大用户。
这时,我们的工作流程发生了小小的变化。但我们仍然使用 Markdown ,将写好的内容提交到仓库供他人审校。当我们的提交被合并之后,Github Pages 网站将会在几秒内自动快速创建并部署。
下面是我们就如何使用 Jekyll 的核心功能以及对 Github 帮助系统起增强效果的插件列了一个简单的纲要。
我们的法宝我们主要依靠 Jekyll 核心代码的功能来完成任务,这样更省心省力,而不是将大量精力用于维护自定义插件。
Jekyll 2.0 提供的全新插件 可以将任何标记自动转换成 HTML。这样用户写文章就可以无拘无束,Jekyll 只负责运行最后生成的 HTML文件就好了。比如,你可以。