Github 是如何使用 Github 来处理 Github 文档的(2)

最后,我们开发了 jekyll-html-pipeline 插件,是我们之前开源的 html-pipeline 在 Jekyll 上的增强版。这个确保了我们的帮助站点的内容在整个Github 上没有任何差异。同时我们也用自己开发的 Markdown filter 插件提供一些语法扩展,进一步降低了文档编写的难度。

搜索

在之前的Rails站点上,我们使用了ElasticSearch 提供商索引我们的数据库并为我们的帮助站点实现了搜索系统。

现在,我们使用lunr-js来提供更加快速的客户端搜索体验。通过我们的分析筛选,我们发现绝大多数的用户依赖于外部搜索服务提供商来获得我们的文档。在迁移期间或者迁移后,将大量的精力花在服务器端的搜索解决方案是没有什么意义的。

内容参考

文档团队希望在编写文档的时候使用“内容参考”。通过内容参考你可以写一大段文字然后在网站任何地方复用它。(这个想法借鉴于 the DITA standard

旧的Rails应用并不能允许我们编写可复用的内容,但是现在我们借助于Jekyll  data files 的力量。举个粒子,我么已经创建了一个叫做conrefs.yml  的文件,并且写了一系列键-值集合的字符串就像下面这样:

repositories:
  create_new:
    1. In the upper-right corner of any page, click {{ octicon-plus Plus symbol }}, and then click **New repository**.
      ![New repository menu](/assets/images/help/repository/repo-create.png)

我们的键根据 (repositories.create_new )特异性进行分组;其对应的值为下面的Markdown源码( "In the upper-right corner...”)。使用使用合适的语法,我们只需要简单一步就能在不同页面引用创建一个新的仓库。

To start the process:
 
{{ site.data.conrefs.repositories.create_new }}
2. Do something else.
3. You're done!

随着Github的界面变化,我们也许需要修改图片或者重新定义方向的指向。这样我们只需要借助内容参考,仅仅在改变一个地方而不是很多地方。

版本化的文档

另一个改变带来的好处是能够提供版本化的帮助文档。随着Github企业版2.0的发布,我们开始提供之前的11.10.340版本和现在的2.0版本这两个不同版本不同的帮助文档内容。为了实现这个,我们在Jekyll站点使用了特别的标志位audience,并在Pages仓库生成HTML时检查这个标志位。

例如,在我们的config.yml文件中,我们设置了一个叫做audience键其值为11.10.340。如果一个特性存在于企业版2.0而不在11.10.340,我们会使用如下语法标记上这一部分:

{% if site.audience != '11.10.340' %}
 
This new feature...
 
{% endif %}

以上的实现仅仅利用了Jekyll的核心功能,我们并不需要为此创建或者维护任何其他的东西。

测试我们的站点

并不是因为站点是静态的我们就可以避免开发测试驱动。

我们第一个测试内容工具一直是 html-proofer。这个工具通过快速得检验我们站点上的每个URL帮助我们核实我们的链接和图片是否正常。

Ruby使用者更加熟悉使用Capybara在他们的测试中模拟网站互动。在我们的静态站点中实现一个类似的工具,这个想法疯狂吗?不!我们的工程师@bkeepers 四年前写了一篇博客讨论了这个问题。这样,我们有能力进行一次更强有力的测试,这测试涵盖我���的内容已和网站行为。比如,我们通过检查YAML文件中的键是否存在确认某个内容是否有效,或者我们会检测Javascript代码是否运行良好。

我们的帮助文档运行在CI上以确保用户不会拿到损坏的内容:

Our help-docs CI build

速度快

内容版权声明:除非注明,否则皆为本站原创文章。

转载注明出处:https://www.heiqu.com/16986.html