當我們釋出一個開源專案的時候，最重要的事情之一就是要建立專案文件。對使用專案的使用者來說，文件是非常有必要的，通常我們可以使用下面這些方式來建立文件：

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/wi

n

下載 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

第一個命令將根據選用的主題，將 sources 目錄中的檔案轉換成靜態網站檔案。第二個命令將啟動一個 Web 伺服器，提供這些靜態網站檔案，我們可以透過 http：//localhost：4000 來訪問：

目前我們的網站看起來還是一個部落格而不是文件，不過我們將要將其改成文件的樣子。

建立一個主題

要改變網站的外觀，我們需要建立一個 hexo 的主題。主題確定了 hexo 生成的網站的樣式和佈局。

https：//

hexo。io/themes/

這個網站有很多免費的 hexo 主題可以使用。但在這篇文章裡，我們要從零開始建立一個 hexo 主題。

Hexo 有一個名為 landscape 的預設主題，在 docs/themes 這個目錄裡面。你可以在 themes 目錄存放多個主題，但每次只能有一個主題被使用。接下來讓我們建立自己的主題。在 themes 目錄下建立一個名為 documentation 的目錄。

Hexo 的主題包含以下檔案和目錄：

_config。yml 主題配置檔案

languages 國際化的語言包

layout 主題佈局，即頁面結構等

scripts 一些 Hexo 外掛指令碼

source 資原始檔夾，裡面的檔名以 _ 開頭外的所有檔案都會被當作網站的靜態資源

我們將建立一個簡單的靜態主題，所以我們不需要 scripts 目錄。然後目前僅以中文展示，所以也不需要 languages 目錄。

我們需要做的就是編寫網站的佈局，以及一些 CSS 程式碼。在本文中我將使Sass 來生成 CSS，但 hexo 並不能直接處理 Sass，但幸運的是有 hexo-renderer-sass 這個外掛來幫助 hexo 處理 Sass。

使用 npm 來安裝 hexo-renderer-sass，在 。/docs（注意不是在 themes 目錄裡面）執行下面的命令：

$ npm install ——save hexo-renderer-sass

然後回到 themes 目錄裡面，配置 Sass，不然 hexo-renderer-sass 外掛不會被載入。在 docs/themes/documentation/_config。yml 檔案中加入下面的程式碼：

node_sass：

outputStyle： nested

precision： 4

sourceComments： false

Sass 的所有可配置在 node-sass

接下來就可以編寫 Sass 程式碼了。不過在本文中我不會詳細介紹怎麼寫 Sass 樣式，因為它和本文內容無關，而且範圍太大，一時半會兒寫不完。你可以在這裡

https：//

github。com/nodejh/hexo-

documentation

找到這些檔案，然後把他們複製到你的專案中，或者你也可以建立自己的樣式。

讓我們繼續回到佈局，開始編寫程式碼之前，還有一個重要的事情就是選擇模板引擎，如 swig、ejs 等。Hexo 預設使用的模版引擎是 swig，這也是我們將要使用的。

接下來建立檔案 docs/themes/documentation/layout/post。swig，並寫入下面的程式碼：

<！DOCTYPE html>

簡單分析一下程式碼。

頭部主要包括兩部分：

title Hexo 提供了一些列的變數，我們可以使用其中的 config。title和 page。title 來組成我們的 title

links 連結裡面包括 normalize CSS，使預設的樣式保持跨瀏覽器的一致性；Google Fonts，使文字顯示更友好；url_for，這是 Hexo 的一個輔助函式，可以在路徑前加上根路徑

接下來看 body 部分，大體上還是 HTML。一些重點部分稍後會詳細介紹。

上面的程式碼會生成網站的選單部分，選單項來自於 site。data。nav 這個物件，稍後我們會在 docs/source/_data/nav。yml 中建立。source/_data 是 Hexo 的資料檔案。site。data。nav 即 _data 目錄中的 nav。yml 檔案。nav。yml 中是一個包含 title 和 items 物件的陣列。

接下來比較重要的是文章內容這部分：

這裡麵包括了文章標題和內容兩部分。文章內容是根據 MarkDown 檔案生成的 HTML。

最後還包括 “上一頁” 和 “下一頁” 按鈕：

{% if page。prev %}

上一頁

{% endif %}

{% if page。next %}

下一頁

{% endif %}

上面的程式碼中，我們假設每個頁面都有 “上一頁” 和 “下一頁” 按鈕。

然後建立一個首頁 documentation/layout/index。swig：

<！DOCTYPE html>

現在差不多就完成了！不僅是佈局檔案完成了，我們的主題也製作好了。最後一件事情就是修改 Hexo 生成靜態檔案的時候使用的主題。修改 docs/_config。yml 檔案中的 theme 屬性：

theme： documentation

所有事情都做完了！接下來我們就可以建立文件了。

編寫文件

接下來就到了整篇文章最重要的部分了，為我們的專案編寫文件。我們將在 docs/source/ 目錄完成這些事情。這裡的文件是網站內容的來源，以及網站的選單。

首先建立選單。Hexo 提供了讓我們定義一些資料檔案，並透過 site。data來訪問。首先在 source 目錄裡面建立 _data 目錄，然後建立名為 nav。yml 的檔案：

- title： Introduction

items：

- id： what-is-it

title： What is it？

- id： how-it-works

title： How it works

- title： Usage

items：

- id： installation

title： Installation

- id： using

title： Using It

這樣我們就可以透過 site。data。nav 來訪問 nav。yml 中的檔案。

在上面建立的選單中，我們建立了兩篇文章，每篇文章有兩個部分。最後我們就只需要建立頁面了。在編寫 MarkDown 之前，先建立以下檔案，與選單對應：

what-is-it。md

how-it-works。md

installation。md

using。md

接下來就要往檔案中寫入內容。檔案的開頭部分是 Front-matter，裡面是頁面的一些設定，Front-matter 是包含在兩個 ——- 之間的 YAML 格式的。

如 what-is-it。md 所示：

——-

layout： default

id： what-is-it

title： What is it？

next： how-it-works。html

——-

This is our what it is markdown file

- one

- two

- three

在 front-matter 中有下面這些設定：

layout 頁面的佈局

id 頁面的唯一標識

title 頁面標題

next 下一頁連結

按照類似的方法編寫其他幾個 MarkDown 檔案。當網站建立好之後，這些 MarkDown 內容會被轉換為 HTML。

編輯好了之後，就可以生成靜態網站了：

$ hexo generate

$ hexo server

然後透過 http：//localhost：4000 就可以看到如下頁面：

部署到 GitHub Pages

現在我們的文件網站就全部做好了，接下來需要做的就是將其部署到 Github Pages 上。如果我們手動來實現，就需要建立 gh-pages 分支，生成靜態網站，複製網站檔案到 gp-pages 分支，commit 並且 push 程式碼到 GitHub。當修改文件之後，又得重複這些工作。

幸運的是，Hexo 提供了一個很方便地將站點部署到 gh-pages 的方法。首先安裝 hexo-deployer-git 這個包，在 docs/ 目錄下執行命令：

$ npm install ——save hexo-deployer-git

然後開啟 docs/_config。yml，在文件的最後面，修改部署配置資訊，注意將其中的使用者名稱（nodejh）修改為你的使用者名稱：

deploy：

type： git

repo： https：//github。com/nodejh/hexo-documentation

branch： gh-pages

message： “Docs updated： {{ now（‘YYYY-MM-DD HH：mm：ss’） }}）”

最後再修改一些其他配置：

# Site

title： Hexo documentation

subtitle： Hexo documentation article

description： Hexo documentation article

author： nodejh

language： zh-cn

timezone： GMT

# URL

url： https：//nodejh。github。io/hexo-documentation

root： /hexo-documentation/

OK！現在就只剩下一件事情了，就是將網站部署到 Github 上，在終端上執行：

$ hexo generate

$ hexo deploy

Hexo 將生成靜態檔案，並將其自動部署到 gh-pages 分支上。部署完成之後，我們就可以透過

https：//

nodejh。github。io/hexo-d

ocumentation

來訪問了。

總結

如果你想要的專案被被人使用，文件是非常必要的。在 GitHub 上也有很多建立專案文件的方法。對於中大型專案來說，維護一個文件網站也是很有必要的。Hexo 不僅能生成靜態網站，同時也提供了部署網站的方案，非常方便我們使用。