当我们颁布一个开源项目的时候，最重要的工作之一就是要创建项目文档。对使用项目的用户来说，文档长短常有须要的，凡是我们可以使用下面这些方法来创建文档：

GitHub Wiki：在 Github 上我们可以为每个项目都创建一个 wiki。Wiki 是由一系列的 Markdown 文件构成，所以我们可以用 wiki 来做项目文档。但这种方案也有一些错误谬误：wiki 的孝敬者不会呈此刻项目孝敬者列表中；文档的布局和构造都是有限制的，只能是 Github Wikis 的样式；文档存储在第三方平台上。

README：我们可以为项目创建一个 README.md 文件，它会直接展示在 Github（或 Gitlab、Coding 等 git 货仓）的项目页面。如果文档非常少，这中方案长短常适合的。但如果文档非常多，这个 README.md 文件就会非常大了。而且凡是来说，README.md 是用来介绍项目，而不是展示文档。

自建网站：固然，我们也可以创建一个文档网站，然后放在本身的处事器上。这样我们就可以随意编纂文档。但这种方案的错误谬误是未便于追踪文档的变革、开发网站和文档维护对比前两种方案麻烦非常多、而且还需要自建主机。

Github Pages：Github 也供给了一个托管项目中静态文件的成果。我们可以为项目创建一个 gh-pages 分支，Github 就会将分支中的内容当做静态站点。这种方案好的一方面是文档维护是在一个单独的分支，虽然可能寻找起来对照麻烦。欠好的一方面是文档编写是编写成静态文件（html/css/js），改削和维护起来对照麻烦。

以上方案都不完美，所以需要一种综合以上所有长处的方案，简单来说就是：

文档以 MarkDown 文件编写

使用 hexo 将 MarkDown 文件生成成静态文件

将静态文件颁布到 github pages

Hexo 简介

Hexo 是一个 Node.js 编写的静态网站生成器。Hexo 主要用来做博客框架，同时 Hexo 也整合了将静态网站部署到 Github 的成果，所以也很适合用来做 Github 项目的文档。

我们可以使用 Hexo，按照写好的 HTML 构造（既 Hexo 的主题），将 MarkDown 文件生成成主题对应的静态 html/css/js 文件。Hexo 供给了将静态文件部署到 Github 分支上的配置。也就是说，我们可以使用 MarkDown 来维护文档，当写好部署配置之后，使用一个命令就可以将文档生成并颁布到 Github 的 gh-pages 分支上。

安置 Hexo

Hexo 是通过 Node.js 编译的，所以需要安置 Node.js。Hexo 使用 Git 将文件部署到 Github，所以也需要安置 Git。

安置 Node.js

保举使用 Node.js 的版本打点器来安置，好比 nvm。固然，也有很多其他的 Node.js 版本打点工具，使用这些工具，我们能很便利地安置 Node.js，以及在差此外 Node.js 的版本中切换。

目前 Node.js 最新的版本是 8.1.3，使用 nvm 来安置：

$ nvm install v8.1.3

安置完 Node.js 的同时也会安置对应的 npm。

安置 Git

我们还需要在系统上安置 Git。如果不确定系统中是否已经安置了 Git，使用下面的命令查抄：

$ git --version

如果呈现了 Git 的版本号，则不需要再安置了。如果没有，则需要安置 Git。

Windows

Windows 系统直接点此连接 https://git-scm.com/download/win 下载 Git 软件，然后运行即可。

macOS

在 macOS 上安置 Git 有多种差此外方法：

Git installer

Homebrew：运行 brew install git

MacPorts：运行 sudo port install git +doc +bash_completion +gitweb

我小我私家保举使用 Homebrew 来安置软件。固然如果你更喜欢 MacPorts，也没有任何问题。

Linux – Ubuntu or Debian

在 Ubuntu 或 Debian 上，我们可以使用 apt 来安置软件：

$ sudo apt-get install git-core Linux – Fedora, Red Hat or CentOS

在 Fedora、Red Hat 或 CentOS 上，我们可以使用 yum 来安置软件：

$ sudo yum install git-core 安置 Hexo CLI

在安置完 Node.js 和 Git 之后，我们最后需要安置 Hexo：

$ npm install -g hexo-cli

通过下面的命令来查抄 hexo 是否正确安置上了：

$ hexo --version

如果输出了一系列的版本号，说明所有安置事情都以完成，可以正式使用 hexo 了。

配置

安置好 hexo 之后，此刻我们就可以在 Github 的主分支上来创建我们的文档了。按照该文章，你可以：

在一个已存在的项目中创建文档

创建一个新的项目 Create a new repository

简单起见，假设你是新创建了一个名为 hexo-documentation 的项目，固然你也可以用一个已经存在的项目继续下面的操纵。

接下来使用下面的名令在本地 clone 项目：

$ git clone https://github.com/USERNAME/REPOSITORY.git

将 USERNAME 替换为你的用户名，REPOSITORY 替换为你的项目名称。例如我执行的命令如下：

$ git clone https://github.com/nodejh/hexo-documentation

然后使用 cd 进入项目目录，并创建一个名为 docs 的目录：

$ cd hexo-documentation $ mkdir docs

docs 目录将存放我们的文档。使用 hexo 初始化 docs 目录：

$ hexo init docs

上面的命令将生成 hexo 的一些配置并安置相关依赖。安置完成之后，docs 的目录布局如下：

_config.yml 站点配置文件

package.json Node.js 的依赖文化

scaffolds hexo 颁布文章的时候使用（本文暂不介绍 hexo 的特性）

source MarkDown 和各类资源文件

themes hexo 的主题

我们可以通过下面的命令来查抄网站是否能够正常运行：

$ hexo generate $ hexo server