天极传媒:
天极网
比特网
IT专家网
52PK游戏网
极客修
全国分站

北京上海广州深港南京福建沈阳成都杭州西安长春重庆大庆合肥惠州青岛郑州泰州厦门淄博天津无锡哈尔滨

产品
  • 网页
  • 产品
  • 图片
  • 报价
  • 下载
全高清投影机 净化器 4K电视曲面电视小家电滚筒洗衣机
您现在的位置: 天极网 > 软件 > 网页>技术文档>用GitHub Pages向用户提供GitHub帮助

如何使用GitHub Pages向用户提供GitHub帮助

天极网软件频道2015-01-13 13:55我要吐槽

  二、新流程

  当 Jekyll 2.0 发布的时候,我们意识到是时候使用静态网站了!特别是 Collections文档类型这个新特性使得定义自己的文件结构成为可能。不仅如此,Jekyll 2.0 还增加了 Sass 和 CoffeeScript 的支持,让前端代码的编写更简单。

  开源的好处在于它是开放的。我们迁移到 Jekyll 后,我们也向 Jekyll项目发起了很多pull requests,贡献代码,使得它能更好的服务 Github Pages 的广大用户。

  这时,我们的工作流程发生了小小的变化。但我们仍然使用 Markdown ,将写好的内容提交到仓库供他人审校。当我们的提交被合并之后,Github Pages 网站将会在几秒内自动快速创建并部署。

  下面是我们就如何使用 Jekyll 的核心功能的方法和步骤,以及为对Github帮助系统起增强效果的插件列了一个简单的纲要。

  我们的法宝

  我们主要依靠 Jekyll 核心代码的功能来完成任务,这样更省心省力,而不是将大量精力用于维护自定义插件。

  Jekyll 2.0 提供的全新插件 Converter 可以将任何标记自动转换成 HTML。这样用户写文章就可以无拘无束,Jekyll 只负责运行最后生成的 HTML文件就好了。比如,你可以使用 AsciiDoc 语法发贴子。

  最后,我们开发了 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

  速度快

  如上所述,比起原来的Rails应用,我们的新Pages实现在速度上有极大的提升。部分原因在于,网站内容主要是大量的静态HTML文件——无需访问数据库。但最重要的是, 我们花费了大量时间来优化Pages服务器使得访问速度狂飙 。另外,包括提供CDN这样的服务条件,我们也能一一满足。

Help docs GA site load times

作者:开源中国社区责任编辑:杨玲)
请关注天极网天极新媒体 最酷科技资讯
扫码赢大奖
评论
* 网友发言均非本站立场,本站不在评论栏推荐任何网店、经销商,谨防上当受骗!
热点推荐
微软Windows 10操作系统Win10系统在Win8的基础上对界面、特性以及跨平台方面做了诸多优化。[详细]
Windows 10 新视界 [进入频道][使用技巧][微博互动]
手机整机DIY企业级