pimgeek / help-doc Goto Github PK

some normal text

  some codes

some other normal text

【目标】我要抽取出 help.github.com 的站点结构
【GTD 结果】已走通

执行参考

@ben7th 的建议：可以在熟悉 help.github.com 站点结构的过程中把它的一些和内容浏览，导航相关的特性，如文章分类，搜索，内部链接外部链接，贴图贴代码（这是我打比方的，实际上有哪些特性按他的为准），各自是如何实现的，和开源工具中的一些用法对应起来，并在记录操作步骤的时候列出。

验收标准

1 主要的页面类型都点过，留有印象
2 主要的页面互动模块和内容模块都看过，留有印象
3 各种模块与开源工具的对应关系要给出
4 配置开源工具的过程中，一些容易踩坑的操作细节要列出

1 主要页面包括

• 主站首页(/)，各个子产品的各版本首页(/sub-prod-name/ver/)，文章页(/articles/)，分类页(/categories/)，搜索页(/search/)

2 各主要页面的主要模块

• 首页以及子产品各版本首页模块列举
  • 置顶文章模块(4个图片链接)
  • 搜索框模块(search)
  • 常见问题模块(common issues)
  • 分类文章列表模块(categories)
• 文章页模块列举
  • 搜索框模块(search)
  • 文章主体模块，其中含若干子模块
    • 不同操作系统的标签页模块(article_platform_nav)，参见 Set Up Git
    • 可折叠的帮助信息模块(helper)，参见 Set Up Git
  • 文章侧边栏模块
    • 同一文章的在其它子产品和版本下的链接
• 分类页模块列举
  • 搜索框模块(search)
  • 文章列表模块(articles)

jekyll + lunrjs 的调通方法已经在 #2 中描述过，所以这里只讲实现 github help 站点文档结构的步骤。

jekyll 环境说明

• 若无特别说明，所有形如 YYYY-MM-DD-article-title.md 文档的 Front Matter 中均含有 title: Article Title，而且 Front Matter 中的 title 与 .md 文件名中的 title 严格对应（不区分大小写），.md 中的 - 严格替换为 。
• 我使用的 jekyll 文件夹名为 help-doc
• 我使用的 jekyll 模板结构大概如下图所示

help-doc/
├── _categories
│   ├── bootcamp.md
│   └── setting-up-and-managing-organizations-and-teams.md
├── _creating_a_new_organization_account
│   ├── 2015-02-08-creating-a-new-organization-from-scratch.md
│   └── 2015-02-09-about-organizations.md
├── css
│   └── ...
├── _data
│   └── conrefs.yml
├── fonts
│   └── ...
├── _includes
│   ├── category-articles.html
│   ├── footer.html
│   ├── header.html
│   ├── head.html
│   ├── search.html
│   ├── sidebar.html
│   └── sub-articles.html
├── _layouts
│   ├── category.html
│   ├── default.html
│   ├── page.html
│   └── post.html
├── _posts
│   ├── 2015-02-10-creating-a-new-organization-account.md
│   ├── 2015-01-01-set-up-git.md
│   └── 2015-01-02-create-a-repo.md
├── _sass
│   └── ...
├── search
│   └── index.html
├── about.md
├── _config.yml
├── feed.xml
└── index.html

利用 jekyll 构建 github help 站点文档结构的步骤描述

• 帮助文档的 markdown 源码要放在哪里，才能通过 Jekyll 输出到前端？
  先编写文档内容，然后按照 YYYY-MM-DD-help-topic.md 的文件格式命名，最后根据实际情况放进以下两个位置：
  • 对于独立的帮助文档，直接放在 _posts 目录下
  • 对于“隶属于”某个独立父帮助文档的“子文档”，根据子文档的实际分类，放在形如 _category_name 这样的目录下

• 如何让 Jekyll 输出类似 https://help.github.com/articles/set-up-git/ 这样的网址？
  编辑 _config.yml 文档，增加/修改这一行：
  permalink: /articles/:title/

• 如何让 Jekyll 输出类似 https://help.github.com/categories/bootcamp/ 这样的分类索引页？
  分多个步骤实现：

  • 在已有的，属于 bootcamp 这一类的帮助文档的 markdown 源码 Front Matter 中增加这段内容：
    categories: ['bootcamp']
    至少要有一篇属于 bootcamp 分类的帮助文档，才能在首页上列出相关的分类。分类名称支持大写字母、小写字母、空格等，但真正存储到 Jekyll 模板系统的内存中时，貌似都会变为小写。
  • 编辑 _config.yml 文档，在其中增加这段定义 collection 的内容：

  collections:
    categories:
      output: true
      permalink: /categories/:path/

  如果不定义这个，仅仅能在首页看到分类索引页的链接，但无法打开目标网页。

  • 在 _categories 目录下创建一个名为 bootcamp.md 的文件（文件名采用大写字母还是小写会造成不同效果，要注意），其内容如下：

  ---
  layout: category
  ---
  
  {% assign cat-title-array=page.url | split:'/' %}
  {% assign cat-title=cat-title-array[2] | replace:'-',' ' %}
  {% assign cat-obj=site.categories[cat-title] %}
  {% include category-articles.html which-cat=cat-obj %}   

  如果不定义这个，或者文件名与分类名不一致，仍然会出现导航中有分类索引页的链接，但实际点不开的情况。如果想定义别的分类，比如 manage-organization 分类，仍然按这个步骤来做，文件内容不变，只有文件名需要改为 manage-organization.md

  • 在 _layouts 目录下创建一个名为 category.html 的网页布局文件，其内容如下：

  ---
  layout: default
  ---
  
  {% assign page-title-array=page.url | split:'/' %}
  {% assign page-title=page-title-array[2] | replace:'-',' ' | capitalize %}
  
  <h1>Category / {{ page-title }}</h1>
  
  {{ content }}

  单个分类索引网页需要引用这个网页布局文件。

  • 在 _include 目录下创建一个名为 category-articles.html 的包含文件，其内容如下：

  <ul>
  {% for post in include.which-cat %}
    <li>
      <a class="post-link" href="{{ post.url | prepend: site.baseurl | prepend: site.url }}">{{ post.title }}</a>
    </li>
  {% endfor %}
  </ul>

  单个分类索引网页需要引用这个网页包含文件。
  关于 {% include tmpl.html var-name=sth %} 和 {{ include.var-name }} 这种特殊语法的介绍，请参考 http://jekyllrb.com/docs/templates/ 中的 ProTip：Use variables as file name

• 如何利用 Jekyll 输出类似于 https://help.github.com/articles/creating-a-new-organization-account/ 这样的 “子文档列表”？
  首先要在 _posts 目录下创建一个独立的父帮助文档：2015-02-10-creating-a-new-organization-account.md，然后进行下列操作步骤：

  • 修改 _config.yml 文件内容，增加一个对应的 collection：

  collections:
  categories:
    output: true
    permalink: /categories/:path/
  creating_a_new_organization_account:  # 这里是新增加的 collection，单词之间必须用 ```_``` 分隔
    output: true
    permalink: /articles/:title/  # 子文档的超链接，以 /articles/xxx-xxx-xxx/ 的方式输出

  • 在独立帮助文档 2015-02-10-creating-a-new-organization-account.md 的 markdown 源码末尾处增加一段获取子文档列表的代码：

  ---
  layout: post
  categories: ['Setting up and managing organizations and teams']
  ---
  
  You can create a new organization by either setting up a new organization or converting an existing personal account into an organization.
  
  {% assign coll-title-array=page.url | split:'/' %}
  {% assign coll-title=coll-title-array[2] | replace:'-','_' | downcase %}
  {% assign coll-obj = site.collections[coll-title].docs %}
  {% include sub-articles.html which-coll=coll-obj %}

  • 在 jekyll 的根目录下创建一个新的 collection 目录： _creating_a_new_organization_account ，这里单词之间必须用 _ 分隔。
  • 在新创建的 collection 目录下增加一系列子文档，均以 markdown 文档方式给出。

  help-doc/
  ├── _creating_a_new_organization_account
  │   ├── 2015-02-08-creating-a-new-organization-from-scratch.md
  │   └── 2015-02-09-about-organizations.md
  

  • 在分类索引页的包含文件 _include/category-articles.html 中增加下列内容

  <ul>
  {% for post in include.which-cat %}
    <li>
      <a class="post-link" href="{{ post.url | prepend: site.baseurl | prepend: site.url }}">{{ post.title }}</a>
        <!-- 如果当前文章有下属的子文章，就顺便列出它们 -->
        {% assign post-id = post.title | replace:' ','_' | downcase %}
        {% if site.collections[post-id].label == post-id %}
          {% assign coll-obj = site.collections[post-id].docs %}
          {% include sub-articles.html which-coll=coll-obj %}
        {% endif %}
       <!-- 子文档列表功能 增加的代码部分结束 -->
    </li>
  {% endfor %}
  </ul>

  • 在 _include 目录下增加一个名为 sub-articles.html 的包含文件，其内容如下

  <ul>
  {% for post in include.which-coll %}
    <li><a class="post-link" href="{{ post.url | prepend: site.baseurl | prepend: site.url }}">{{ post.title }}</a></li>
  {% endfor %}
  </ul>

  分类索引文件和独立的父文档文件都需要引用这个包含文件。

• 如何实现 github help 文档中的 conrefs 内容复用？

  • 首先在 jekyll 的源码目录下创建一个 _data 目录
  • 在 _data 目录下创建 conrefs.yml 文件，其内容根据实际需要而定

  repositories:
  create-new:
    1. In the upper-right corner of any page, click {{ octicon-plus }}, and then click **New repository**.
      ![New repository menu](https://help.github.com/assets/images/help/repository/repo-create.png)
  
  wiki:
  click-profile:
    1. ![Profile photo](/assets/images/help/profile/top_right_avatar.png)In the top right corner of any page, click your profile photo, then click **Your profile**.           

  这些就是未来将会被复用的内容片段，只要修改 conrefs.yml 文件，并且用 jekyll 重新 build 全站文档，就可以做到一处修改多处生效。

  • 在实际的帮助文档的 markdown 源码中引用这些片段：

  ### Create a new repository on GitHub                                                                 
  
  {{ site.data.conrefs.repositories.create-new }}
  2. 
  ![Repository name field](/assets/images/help/repository/create-repository-name.png)Create a short, memorable name for your repository. For example, "hello-world".                                                     

  将会被替换为下图所示的样子
  

【目标】尝试把 jekyll 与 lunrjs 串接起来使用，实现纯前端全文搜索
【GTD 结果】已走通，只是不支持中文搜索

验收标准：

1 要说明每个尝试步骤的要点
2 要说明尝试实际操作的结果如何
3 要把已经走通的步骤中比较关键的操作细节记录下来

jekyll + lunrjs 操作步骤

特别说明：我只是按下列方法调通了，但更多细节还需参考原始网站 - https://github.com/slashdotdash/jekyll-lunr-js-search

01 - gem install jekyll

02 - gem install jekyll-lunr-js-search

03 - jekyll new lunr

04 - 编辑 _config.yml ，增加下列代码

gems: ['jekyll-lunr-js-search']

05 - 在 _include/ 目录下创建 search.html 模板

<div id="search">
  <form action="{{ site.baseurl }}/search" method="get">
    <input type="text" id="search-query" name="q" placeholder="Search" autocomplete="off">
  </form>
</div>
<section id="search-results" style="display: none;">
  <p>Search results</p>
  <div class="entries">
  </div>
</section>
{% raw %}
<script id="search-results-template" type="text/mustache">
  {{#entries}}
    <article>
      <h3>
        {{#date}}<small><time datetime="{{pubdate}}" pubdate>{{displaydate}}</time></small>{{/date}}
        <a href="{{{ site.baseurl }}}{{url}}">{{title}}</a>
      </h3>
    </article>
  {{/entries}}
</script>
{% endraw %}
<script src="{{ site.baseurl }}/js/search.min.js" type="text/javascript" charset="utf-8"></script>
<script type="text/javascript">
  $(function() {
    $('#search-query').lunrSearch({
      indexUrl: '{{ site.baseurl }}/js/index.json',   // Url for the .json file containing search index data
      results : '#search-results',  // selector for containing search results element
      entries : '.entries',         // selector for search entries containing element (contained within results above)
      template: '#search-results-template'  // selector for Mustache.js template
    });
  });
</script>

06 - 在需要提供搜索功能的模板中增加下列代码

{% include search.html %}

07 - 创建 search/ 目录并创建搜索页模板 index.html

---
layout: page
title: Search

---

{% include search.html %}

08 - 在 _posts/ 目录下放置一些 markdown 文档
例如：yyyy-mm-dd-postname.md

09 - 执行 jekyll serve -H 0.0.0.0 预览效果
例如：http://192.168.1.32/

10 - 部署到 github pages（project 类站点）前的准备
修改 _config.yml
baseurl: "/help-doc/v001"
注释掉 url: 这一行
然后修改以下模板文件 _include/search.html 中的相关路径
特别是 {{url}}这一行要改为

<a href="/help-doc/v001{{url}}">{{title}}</a>

再次执行 jekyll serve -H 0.0.0.0 预览效果
例如：http://192.168.1.32/help-doc/v001/

11 创建一个新的版本库 https://github.com/username/help-doc
然后先 clone 到本地，再创建并切换到 gh-pages 分支，再
在其中创建 v001 目录。

12 把 _site 中的静态文件完全复制到 help-doc 源码库的 v001 目录下
执行 git add / commit / push origin gh-pages 等命令
稍等片刻，就可以用 yourname.github.io/help-doc/v001 访问之。
例如：http://pimgeek.github.io/help-doc/v001/
简单试用过后，发现 lunrjs 无力对中文内容做索引

有个号称支持中文分词的 luna.js 我曾试着替换 jekyll 项目中的 js 文件，但没有调通。具体步骤略。

参考资料

Jekyll 的 lunajs 搜索插件 - https://github.com/slashdotdash/jekyll-lunr-js-search
一个使用 lunrjs 的典型博客 - https://github.com/rohit01/rohit01.github.io
一个号称支持中文分词的 lunr.js - https://github.com/nandy007/lunr.js