有很多知名的项目，例如 webpack，会把自己的文档托管在 .js.org 域名下面。作为前端开发者，如果拥有一个 .js.org 为后缀的域名网站，确实是一件很酷的事。那么，怎么才能拥有一个 .js.org 域名的网站呢？我在实践之后，把这个过程写下来给你，希望对你有用。

Js.org 项目介绍

这是一个很酷的项目，项目的发起人注册了 js.org 域名，并且免费提供给前端开发者使用它的二级域名。你可以在这里了解它的所有，同时，你还可以在 github 上关注他们。那么，这究竟是一个怎样的项目呢？

实际上，我们抛开他们的技术实现，它就是一个域名服务。和我们以前注册域名，并绑定到自己的主机上一模一样。

只是，它的操作过程比一般的域名服务（域名注册和解析）麻烦很多。

由于这个域名的特殊性，几乎知会有前端开发者去申请使用它。而这些使用该服务的开发者，很大一部分和我一样，用它来作为自己项目的一个文档服务，给其他人阅读自己开发的库或框架如何使用。但是，实际上，作为域名服务，它根本不挑剔它所指向的，是一个文档服务，还是一个其他任何类型的应用。你可以试试这个网址，再看看它用 js.org 之后的效果。你可以发现，这个搭在其他服务器上的网站，通过将 js.org 域名绑定到自己的主机，就可以让访客用 js.org 域名访问自己的网站了。因此，js.org 真的只是一个域名服务而已，不需要觉得它非常麻烦，是一个有多高门槛的服务。

创建自己的 github pages

作为开发者，怎么能没有一个自己的主页呢？当然，你可以使用自己的服务器，搭建一个像我一样的 wordpress 个人网站，这当然可以。但是，服务器，每个月都需要一定的费用。而使用 github pages 则不需要费用，它是免费的。github 给每一个开发者提供了一个免费的 github.io 子域名，二级域名名称就是开发者的注册 id，在你开通 github pages 服务之后，就可以使用这个子域名了。

那么，如何创建自己的 github pages 呢？按照如下步骤操作即可。

第一步，确定要用来作为 pages 的项目。

在 github 上创建一个新项目，作为要放 pages 的项目。很多个人博客就是这么干的，那些博主在自己的 github 上创建了一个名字叫 xxx.github.io 的项目，然后将自己的网站源码 push 到这个项目中。（这里需要注意，pages 服务只接受静态资源，你如果需要进行数据存储，只能采用前后端分离的方式，将数据存放到另外一个地方去，gh-pages(github pages) 只支持静态资源服务。）

除了上面这种方式。假如你和我一样，想要给单个项目创建一个文档服务，那么，你可以有两种选择：1）在项目 master 分支根目录下方创建一个 docs 目录，用于存放文档；2）创建一个新分支 gh-pages 作为存放文档的独立分支。我选择了第一种，因为对于要访问我项目的其他人而言，他们可以点击 docs 目录，进去查看我写的文档，而无需切换分支。

这里相当于给了你 3 种选择。那么如何选择呢？一般而言：a. 当你要创建一个个人/机构主页时，创建一个 xxx.github.io 的项目；b. 当你在给一个项目创建主页时，使用该项目的 gh-pages 分支；c. 当你在给一个项目创建主页时，使用 master 分支下的 docs 目录。

个人/机构主页和项目主页的区别是，个人/机构主页网址就是域名，而项目主页的网址是域名后面还根上了项目名。这也是为什么很多项目单独注册了一个机构，而非直接挂在作者自己的名字下。其中 b 和 c 看上去没啥差别，但差别还是有，如果你多出一个 docs 目录，可能影响你项目代码但纯净性，这种时候，使用一个独立分支单独存放项目主页代码，会使项目源码比较干净。

第二步，上传网站文件。

无论你选择了哪一种方式，你需要在每一种方式的根目录下，放一个 index.html 作为首页。（docs 目录作为 gh-pages 时，把 index.html 放在 docs 目录下。因为只允许提供静态资源，所以，基本上，你只能靠 js 来完成编程了。

完成网站的制作后，把对应的内容 push 到仓库中。

第三步，开启 pages 服务。

你已经完成了前两步。接下来，我们开启 pages 服务。点击项目顶部导航中的 Settings 菜单，

往下拉，找到 GitHub Pages 这个部分，

选择对应的 Source 选项。在最新版的 github 后台，点击其中一个选项之后，会自动刷新页面，并且提示你 pages 已经发布成功，你可以访问网页上出现的网址进行访问。

➡ 根据官方提示，只有在管理员的 push 才能触发 pages 网站的更新，因此要额外注意这一点。

现在，你可以使用 yourname.github.io/yourproject 访问你的 pages 主页了。

域名绑定

对于 gh-pages 服务，它本身和 js.org 服务没有半毛钱关系。你可以把 gh-pages 当作是你自己的博客，现在，你可以使用其他域名绑定到 gh-pages 的主页上。

第一步，CNAME 文件。

在文档根目录创建一个名为 CNAME 的文件，在这个文件中，其内容必须只能是你要绑定的域名。例如我，就在 CNAME 文件中，只写入如下内容：

nautil.js.org

然后将更新后的 pages 文件 push 到项目中。 经过测试，你不需要自己创建这个 CNAME 文件，而是在执行下一步时自动帮你生成这个 CNAME 文件。

这个时候，当你再访问 github 给你默认配的域名地址时，你会发现，网址发生了跳转。

第二步，绑定域名。

理论上，CNAME 被 push 之后，github 应该自动给我做域名绑定。但是实际上，并没有，CNAME 文件似乎只是为了实现跳转。而要将我们自己的域名绑定到 gh-pages 服务上，还必须在刚才操作的设置页面，填写要绑定的域名（必须和 CNAME 中的一致）。

填写好，点击 Save 之后，在 github 所要做的事情就完成了。

第三步，域名解析。

如果你不是使用 js.org 域名，你需要到你的 dns 服务商处去修改对应的解析记录。这条解析记录应该是一个指向 yourname.github.io 的 CNAME 记录。

当然，如果你要使用 js.org 域名，请继续往下读。

申请和绑定 js.org 域名

首先，你可以到 js.org 这个网站去看看，因为它本身就已经教你如何操作了。接下来，你需要按照下面的步骤进行。

第一步，fork 仓库。

进入 js.org 的主仓库，点击右上角的 Fork 按钮。稍等一下刷新页面。这样，这个仓库就被 fork 到你自己的名下。

第二步，修改代码。

将 fork 过来到仓库 clone 到本地，然后用编辑器打开，找到 cnames_active.js 文件，在里面看一下，大概知道怎么回事了吧。添加你想要到二级域名，以及 CNAME 到的网址。注意，大家的约定都是按字母顺序排序的。照葫芦画瓢改好代码。push 回 github。

第三步，Pull Request。

回到你 fork 的仓库页面，找到一个叫 Pull Request 的按钮。点击它，提交。

这样就完成了域名申请和绑定了。是不是很简单。接下来的事情，就是等待，因为中美之间的时差关系，你最好在晚上 12 点之前完成上面这些操作（根据indus的提醒，他实际上是在德国工作，因此时间比我们早）。等美国那边的项目维护者上线之后，就会对你的 pull request 进行检查，如果没有问题，就会 approve，一切顺利，就会 merge，之后很快你就可以用拿到的域名访问你的 gh-pages 了。

如果你有兴趣，还可以继续看看 ns_active.js，看完之后，你就能再次明白，js.org 就是一个域名服务项目啊。

使用 docsify

这也是一个超级酷的项目，专门为前端开发者写 gh-pages 而生。这个项目本身是用 vue 实现的，但是它的使用极其方便，让你感受到封装是多么爽的一件事。为什么要使用 docsify 这个项目呢？因为它实在是太方便了，它的初衷，就是为 github 上的项目写文档而设计的。

我们在项目中怎么写文档？当然是用 markdown 来写。如果你要发布一个网页来组织文档，怎么想都会很麻烦，比如直接用 html 写，不现实；比如用 md 写完之后，本地用一个工具转为 html，例如 gitbook 做的，也不如意。而 docsify 直接通过解析 md 文档来实现渲染。你写文档就是写 md 文件，不用做任何修改。只是，在你的 docs 目录下，再加一个 index.html 即可。在这个 index.html 文档中，我们直接使用 docsify 的 CDN 文件，然后整个 pages 网站就渲染好了。

你可以阅读 nautil 的文档主页，然后查看源码，就可以发现，原来事情如此简单。

小结

本文啰啰嗦嗦讲了一大通，讲明白了 github pages 服务和 js.org 服务，这两个服务的使用方法，以及整篇文章联系起来，如何快速给你的项目发布一个在线文档的途径。虽然没有什么技术含量，但是对于那些有这方面需要的小伙伴，应该也是相见恨晚吧。

2020-03-08 8274 github