文档自动排序长短_用Github Page快速创建项目文档网站

本文分为3个部分：

1. 如何为你的项目快速搭建文档网站？（基于GitHub Pages和RunDocs）
2. 如何将基于Github Pages的网页映射到自定义域名上？
3. 【重要且难缠，欢迎讨论】如何处理当前境内运营商将*.http://github.io错误的解析到127.0.0.1导致基于Github Page的网页很难在境内访问的问题（访问报错*.http://github.io拒绝访问/拒绝连接）

1. 如何为你的项目快速搭建文档网站？（基于GitHub Pages和RunDocs）

如果你也遇到了下列困难，那么阅读这一章节可以帮你省下很多初学者走弯路的时间：

• 给你的项目写文档的时候，文档篇幅长导致ReadMe.md可读性差？this is for you~
• 想让你的Github项目也能有自己的文档网站，但苦于没前端背景、云服务器太贵，想要一个像markdown一样简单、免费的创建项目文档网站的方法？this is for you~
• 如果你已经知道了GitHub Pages，但官方教程里基于单个markdown的单一网页满足不了你的需求、第一次建站的你又被jekyll的教程弄的一头雾水（比如怎么加侧边导航栏），this is for you~

基于GitHub Pages（网页服务）和RunDocs（网站模板）可以让你在5分钟内就建好你的项目文档网站！！！而且有动态导航栏、支持较复杂的文档结构！！！而且基本没有学习成本！！！基本上唯一需要的就是熟悉markdown和github的日常使用了。在这里感谢Github Page和RunDocs ！orzzzzz

RunDocs的模板如下图，这种风格在很多知名Python库的文档网页上都可以看到，依照本文可以快速生成下面样式的文档网站。

建站步骤分成如下几步：

• 1.1 Github Page设置
• 1.2 RunDocs设置
• 1.3 文档层级设计和文档内容文件放置

1.1 Github Page设置

注意：

• 这部分官方文档解释的很详细Creating a GitHub Pages site - GitHub Docs，但为了完整还是简单叙述一下；
• Github Page可以对应单个repository也可以对应整个Github账号，本文仅针对为单个repo创建Github Page作为文档网页的场景，但方法是transferable的~

首先，在项目的repository新建文件夹`docs`创建分支`gh-pages`，用于存放网页相关的文件（如果没有repo参考github page官网教程）；

随后，在项目repo的主页点击Settings，进入Options界面向下拉，找到"Github Pages"部分，将publishing source设置为在上一步新建的docs文件夹或gh-pages分支，随后点击choose a theme为网页选择主题，随便选个默认的就好，后面反正会改成RunDocs的主题，完成后就可以看到只有标题的网页了~下面的custom domain是用来设置github page的自定义域名的，目前先不用理会。

现在你的Github Page网站就初步建好啦（虽然还没内容），成功的标志是repo的setting/options/Github Pages部分，有一条高亮的消息“Your site is published at ......”，这个就是目前网页的网址了~

1.2 RunDocs设置

RunDocs和jekyll的官方文档其实非常详细，使用方法也非常简单，但是对于初学者而言缺失了0到1的部分（可能作者觉得这部分太self-explained了），笔者花了些时间才弄清楚应该怎么组织多层级的网页，希望下面的部分能作为官方文档的补充，让刚起步的你走的轻松点~

此前介绍了docs文件夹和gh-pages分支两种存储网页相关文件的方式，下面均以docs为例介绍。

首先将项目pull到本地方便操作，随后按RunDocs官方教程，在docs文件夹中创建下面四个文件（Gemfile和Makefile没有后缀），这些文件设置了网页的主题等信息，如果docs已经有了同名文件可以直接覆盖：

（PS, 官方教程Gemfile · RunDocs结合官方Github示例rundocs.io食用更佳）

这四个文件的内容如下：

Gemfile

source "https://gems.ruby-china.com"
gem "jekyll-rtd-theme"

gem "github-pages", group: :jekyll_plugins

Makefile

DEBUG=JEKYLL_GITHUB_TOKEN=blank PAGES_API_URL=http://0.0.0.0

default:
	@gem install jekyll bundler && bundle install

update:
	@bundle update

clean:
	@bundle exec jekyll clean

build: clean
	@${DEBUG} bundle exec jekyll build --profile --config _config.yml,.debug.yml

server: clean
	@${DEBUG} bundle exec jekyll server --livereload --config _config.yml,.debug.yml

_config.yml

title: Your project name
lang: en
description: a catchy description for your project

remote_theme: rundocs/jekyll-rtd-theme

readme_index:
  with_frontmatter: true

exclude:
  - Makefile
  - CNAME
  - Gemfile
  - Gemfile.lock

.debug.yml

remote_theme: false

theme: jekyll-rtd-theme

1.3 文档层级设计和文档内容文件放置

下面会结合实际案例，介绍一下RunDocs模板的核心玩法~

（如果有不够直观的地方，可以阅读的同时，参考我的Github Page或RunDocs官方案例）

首先docs文件夹下，放置一个README.md文件，访问者一点开页面，就能看到这个markdown文档的内容，通常可用放一下整个项目的简介以及子页面的跳转链接，链接的语法用[文本](链接)；

docs文件夹的子文件夹对应了左侧导航栏的一级页面（下图红圈），下面介绍如何创建。

下图展示了/docs文件夹的全貌，Chinese, English, Notebooks, API均为一级页面，分别对应上图的四个一级页面“中文文档”、“English Document”、“Example Notebooks”、“API Reference”。下面将介绍如何创建一级页面和下属的二级页面

子文件夹中的README.md文件是一级页面命名和排序的关键：

• 创建子文件夹后创建README.md，显示点击一级页面后会显示的内容；
• 首先在前三行中写明，代表这个一级页面排在左侧导航栏的第1个（第二个一级页面就改成2，以此类推），这部分代码不会显示在网页上

---
sort: 1
---

• 子文件夹中的README.md的第四行写markdown的一级标题，作为一级页面在导航栏中显示的文本，例如下图设置了一级页面“中文文档”在左侧导航栏的排序和名称

• 设置一级页面下的子页面的跳转连接（如果需要），可以用官方推荐的方法在markdown里添加{% include list.liquid %}这将自动抓取这个文件夹下的子页面的标题； 或用markdown语法`[文本](链接)`写明链接的名称，个人倾向于后者。

为一级页面创建二级子页面

• 每个二级子页面就是这个一级页面文件夹下的markdown文件，文件名不限；
• 二级子页面的markdown文件的结构与一级页面的README.md类似，首先通过sort定义二级子页面的排序，子页面的名称由该markdown的一级标题定义，markdown二级标题、三级标题会变成子页面的下属二级、三级页面

下图展示了一级页面“中文文档”文件夹，README.md用于此一级页面的排序和命名，1.intro.md和2.usage.md分别是两个子页面（文档开头的sort分别为1和2，代表子页面的排序），如果需要，可以去Github查看详细文件内容 文件夹“中文文档”

2. 如何将基于Github Pages的网页映射到自定义域名上？

首先要有一个经实名认证、配置了DNS解析服务的域名，可以在腾讯云/阿里云等服务商注册和配置。我注册的域名是bubu.blue

为你的项目设计一个二级域名，我的是scorecard-bundle.bubu.blue,填写到项目的repo的setting/options/Github Pages/custom domain部分，点save, 勾选enforce https使得最终的网站可以通过https访问。

在docs文件夹下新建CNAME文件，无后缀，文件内容就是二级域名：scorecard-bundle.bubu.blue。

最后，在域名的服务商的控制台的域名解析页面，添加CNAME解析记录，主机填二级域名的名称（我的例子中是scorecard-bundle)，映射的目标是第一步已经创建成功的github page的域名 xxxx.github.io. （注意结尾要跟一个英文句号）

然后等最多10分钟，就可以通过自定义的域名访问网页啦~成功的标志跟之前一样，repo的setting/options/Github Pages部分，有一条高亮的消息“Your site is published at ......”

注意！！！最近境内访问Github Page有时候会有问题，解决方法请继续往下看~

3.【重要且难缠，欢迎讨论】如何处理当前境内运营商将*.http://github.io错误的解析到127.0.0.1导致基于Github Page的网页很难在境内访问的问题（访问报错*.http://github.io拒绝访问/拒绝连接）

笔者搭了github page后通过自定义域名解析到了自己的二级域名上，发现不用vpn经常就访问不了（访问报错xxxx拒绝访问/拒绝连接），经过查资料和研究，问题的原因应该是http://xxxx.github.io这个域名被解析成本地ip 127.0.0.1（虽然网站解析到了自己的域名，但背后还是github page的github.io域名），目前我按下面的方法设置一下域名解析就解决了，但我在这个领域比较小白，不确定这么做会不会有什么隐患，比如IP过段时间会不会失效？。。。先分享出来 ，欢迎大家指正。

解决方案：github page自定义域名需要在域名提供商的控制台设置CNAME的解析，但有的运营商会吧http://xxxx.github.io解析成127.0.0.1导致无法访问，我们可以先确定http://xxxx.github.io的真实ip，为境内用户添加映射到这个真实ip的A记录（线路选境内，因为主要是境内访问有这个问题，境外可以正常访问），然后问题就解决了~ 我是通过站长之家查询到我的域名对应了4个IP，把其中的两个设置成了境内的A记录解析（腾讯云的免费DNS解析最多两个A记录）

PS: 原来的CNAME解析可以保留，所以我现在为这个二级域名设置了3个解析，一个CNAME解析到http://xxx.github.io，两个针对境内的A解析到http://xxx.github.io对应的两个IP上

PPS: 个人猜想，很多博客正常可能是由于映射到了一级域名上，直接添加了A记录的解析所以就避开了运营商把http://xxx.github.io错误的解析为127.0.0.1的问题