使用 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 上，在终端上运行：

$ hexo generate
$ hexo deploy

Hexo 将生成静态文件，并将其自动部署到 gh-pages 分支上。部署完成以后，咱们就能够经过 https://nodejh.github.io/hexo-documentation 来访问了。

总结

若是你想要的项目被被人使用，文档是很是必要的。在 GitHub 上也有不少建立项目文档的方法。对于中大型项目来讲，维护一个文档网站也是颇有必要的。Hexo 不只能生成静态网站，同时也提供了部署网站的方案，很是方便咱们使用。

使用 Hexo 建立项目文档网站