使用 Hexo 建立項目文檔網站

時間 2019-11-09

標籤使用 hexo 建立項目文檔網站欄目網站開發简体版

原文原文鏈接

當咱們發佈一個開源項目的時候，最重要的事情之一就是要建立項目文檔。對使用項目的用戶來講，文檔是很是有必要的，一般咱們可使用下面這些方式來建立文檔：css

GitHub Wiki：在 Github 上咱們能夠爲每一個項目都建立一個 wiki。Wiki 是由一系列的 Markdown 文件組成，因此咱們能夠用 wiki 來作項目文檔。但這種方案也有一些缺點：wiki 的貢獻者不會出如今項目貢獻者列表中；文檔的結構和佈局都是有限制的，只能是 Github Wikis 的樣式；文檔存儲在第三方平臺上。html
README：咱們能夠爲項目建立一個 README.md 文件，它會直接展現在 Github（或 Gitlab、Coding 等 git 倉庫）的項目頁面。若是文檔很是少，這中方案是很是適合的。但若是文檔很是多，這個 README.md 文件就會很是大了。並且一般來講，README.md 是用來介紹項目，而不是展現文檔。node
自建網站：固然，咱們也能夠建立一個文檔網站，而後放在本身的服務器上。這樣咱們就能夠隨意編輯文檔。但這種方案的缺點是不便於追蹤文檔的變化、開發網站和文檔維護相比前兩種方案麻煩很是多、並且還須要自建主機。git
Github Pages：Github 也提供了一個託管項目中靜態文件的功能。咱們能夠爲項目建立一個 gh-pages 分支，Github 就會將分支中的內容當作靜態站點。這種方案好的一方面是文檔維護是在一個單獨的分支，雖然可能尋找起來比較麻煩。很差的一方面是文檔編寫是編寫成靜態文件（html/css/js），修改和維護起來比較麻煩。github

以上方案都不完美，因此須要一種綜合以上全部優勢的方案，簡單來講就是：web

文檔以 MarkDown 文件編寫ajax
使用 hexo 將 MarkDown 文件生成成靜態文件npm
將靜態文件發佈到 github pagesjson

Hexo 簡介

Hexo 是一個 Node.js 編寫的靜態網站生成器。Hexo 主要用來作博客框架，同時 Hexo 也整合了將靜態網站部署到 Github 的功能，因此也很適合用來作 Github 項目的文檔。api

咱們可使用 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

第一個命令將根據選用的主題，將 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>
<html>
<head>
  <meta charSet='utf-8' />
  <title>{{config.title + ' - ' + page.title}}</title>
  <link href='https://cdnjs.cloudflare.com/ajax/libs/normalize/4.0.0/normalize.min.css' rel='stylesheet' type='text/css'>
  <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,600,300,700' rel='stylesheet' type='text/css'>
  <link href='{{ url_for("css/docs.css") }}' rel='stylesheet'>
</head>
<body>
  <div class='menu'>
    <div class='logo'>
      Documentation
    </div>
    <nav class='menu-nav'>
      {% for section in site.data.nav %}
        <ul class='nav'>
          <span>{{ section.title }}</span>
          <ul class='nav'>
            {% for item in section.items %}
              <li>
                <a href='{{item.href || url_for(item.id + ".html") }}'{% if item.id == page.id %} class='active'{% endif %}>{{item.title}}</a>
              </li>
            {% endfor %}
          </ul>
        </ul>
      {% endfor %}
    </nav>
    <a class='footer' href='https://github.com/sitepoint-editors/hexo-documentation'>
      Project on github
    </a>
  </div>
  <div class='page'>
    <div class='page-content'>
      <h1>{{page.title}}</h1>
      {{page.content}}
    </div>
  </div>
  <div class='switch-page'>
    {% if page.prev %}
      <a class='previous' href='{{ url_for(page.prev) }}'>Previous</a>
    {% endif %}
    {% if page.next %}
      <a class='next' href='{{ url_for(page.next) }}'>Next</a>
    {% endif %}
  </div>
</body>
</html>

簡單分析一下代碼。

<head>
  <meta charSet='utf-8' />
  <title>{{config.title + ' - ' + page.title}}</title>
  <link href='https://cdnjs.cloudflare.com/ajax/libs/normalize/4.0.0/normalize.min.css' rel='stylesheet' type='text/css'>
  <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,600,300,700' rel='stylesheet' type='text/css'>
  <link href='{{ url_for("css/docs.css") }}' rel='stylesheet'>
</head>

頭部主要包括兩部分：

title Hexo 提供了一些列的變量，咱們可使用其中的 config.title 和 page.title 來組成咱們的 title
links 連接裏面包括 normalize CSS，使默認的樣式保持跨瀏覽器的一致性；Google Fonts，使文本顯示更友好；url_for，這是 Hexo 的一個輔助函數，能夠在路徑前加上根路徑

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

<nav class='menu-nav'>
  {% for section in site.data.nav %}
  <ul class='nav'>
    <span>{{ section.title }}</span>
    <ul class='nav'>
      {% for item in section.items %}
        <li>
          <a
            href='{{ item.href || url_for(item.id + ".html") }}'
            {% if item.id == page.id %}
              class='active'
            {% endif %}
          >
            {{ item.title }}
          </a>
        </li>
      {% endfor %}
    </ul>
  </ul>
  {% endfor %}
</nav>

上面的代碼會生成網站的菜單部分，菜單項來自於 site.data.nav 這個對象，稍後咱們會在 docs/source/_data/nav.yml 中建立。source/_data 是 Hexo 的數據文件。site.data.nav 即 _data 目錄中的 nav.yml 文件。nav.yml 中是一個包含 title 和 items 對象的數組。

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

<div class="page-content">
  <h1>{{ page.title }}</h1>
  {{ page.content }}
</div>

這裏麪包括了文章標題和內容兩部分。文章內容是根據 MarkDown 文件生成的 HTML。

{% if page.prev %}
  <a class='previous' href="{{ url_for(page.prev) }}">上一頁</a>
{% endif %}
{% if page.next %}
  <a class='next' href="{{ url_for(page.next) }}">下一頁</a>
{% endif %}

上面的代碼中，咱們假設每一個頁面都有「上一頁」和「下一頁」按鈕。

而後建立一個首頁 documentation/layout/index.swig：

<!DOCTYPE html>
<html>
<head>
  <meta charSet='utf-8' />
  <title>{{config.title + ' - ' + page.title}}</title>
  <link href='https://cdnjs.cloudflare.com/ajax/libs/normalize/4.0.0/normalize.min.css' rel='stylesheet' type='text/css'>
  <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,600,300,700' rel='stylesheet' type='text/css'>
  <link href='{{ url_for("css/docs.css") }}' rel='stylesheet'>
</head>
<body>
  <div class='index'>
    <a href="/what-is-it.html">
      Get Start
    </a>
  </div>
</body>
</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 上，在終端上運行：