使用 Hexo 創(chuàng)建項(xiàng)目文檔網(wǎng)站

mikasa 發(fā)布于2019-08-01 17:05 / 743人閱讀

摘要：而且通常來說，是用來介紹項(xiàng)目，而不是展示文檔。如果不確定系統(tǒng)中是否已經(jīng)安裝了，使用下面的命令檢查如果出現(xiàn)了的版本號(hào)，則不需要再安裝了。例如我執(zhí)行的命令如下然后使用進(jìn)入項(xiàng)目目錄，并創(chuàng)建一個(gè)名為的目錄目錄將存放我們的文檔。

當(dāng)我們發(fā)布一個(gè)開源項(xiàng)目的時(shí)候，最重要的事情之一就是要?jiǎng)?chuàng)建項(xiàng)目文檔。對(duì)使用項(xiàng)目的用戶來說，文檔是非常有必要的，通常我們可以使用下面這些方式來創(chuàng)建文檔：

GitHub Wiki：在 Github 上我們可以為每個(gè)項(xiàng)目都創(chuàng)建一個(gè) wiki。Wiki 是由一系列的 Markdown 文件組成，所以我們可以用 wiki 來做項(xiàng)目文檔。但這種方案也有一些缺點(diǎn)：wiki 的貢獻(xiàn)者不會(huì)出現(xiàn)在項(xiàng)目貢獻(xiàn)者列表中；文檔的結(jié)構(gòu)和布局都是有限制的，只能是 Github Wikis 的樣式；文檔存儲(chǔ)在第三方平臺(tái)上。

README：我們可以為項(xiàng)目創(chuàng)建一個(gè) README.md 文件，它會(huì)直接展示在 Github（或 Gitlab、Coding 等 git 倉庫）的項(xiàng)目頁面。如果文檔非常少，這中方案是非常適合的。但如果文檔非常多，這個(gè) README.md 文件就會(huì)非常大了。而且通常來說，README.md 是用來介紹項(xiàng)目，而不是展示文檔。

自建網(wǎng)站：當(dāng)然，我們也可以創(chuàng)建一個(gè)文檔網(wǎng)站，然后放在自己的服務(wù)器上。這樣我們就可以隨意編輯文檔。但這種方案的缺點(diǎn)是不便于追蹤文檔的變化、開發(fā)網(wǎng)站和文檔維護(hù)相比前兩種方案麻煩非常多、而且還需要自建主機(jī)。

Github Pages：Github 也提供了一個(gè)托管項(xiàng)目中靜態(tài)文件的功能。我們可以為項(xiàng)目創(chuàng)建一個(gè) gh-pages 分支，Github 就會(huì)將分支中的內(nèi)容當(dāng)做靜態(tài)站點(diǎn)。這種方案好的一方面是文檔維護(hù)是在一個(gè)多帶帶的分支，雖然可能尋找起來比較麻煩。不好的一方面是文檔編寫是編寫成靜態(tài)文件（html/css/js），修改和維護(hù)起來比較麻煩。

以上方案都不完美，所以需要一種綜合以上所有優(yōu)點(diǎn)的方案，簡(jiǎn)單來說就是：

文檔以 MarkDown 文件編寫

使用 hexo 將 MarkDown 文件生成成靜態(tài)文件

將靜態(tài)文件發(fā)布到 github pages

Hexo 簡(jiǎn)介

Hexo 是一個(gè) Node.js 編寫的靜態(tài)網(wǎng)站生成器。Hexo 主要用來做博客框架，同時(shí) Hexo 也整合了將靜態(tài)網(wǎng)站部署到 Github 的功能，所以也很適合用來做 Github 項(xiàng)目的文檔。

我們可以使用 Hexo，根據(jù)寫好的 HTML 布局（既 Hexo 的主題），將 MarkDown 文件生成成主題對(duì)應(yīng)的靜態(tài) html/css/js 文件。Hexo 提供了將靜態(tài)文件部署到 Github 分支上的配置。也就是說，我們可以使用 MarkDown 來維護(hù)文檔，當(dāng)寫好部署配置之后，使用一個(gè)命令就可以將文檔生成并發(fā)布到 Github 的 gh-pages 分支上。

安裝 Hexo

Hexo 是通過 Node.js 編譯的，所以需要安裝 Node.js。Hexo 使用 Git 將文件部署到 Github，所以也需要安裝 Git。

安裝 Node.js

推薦使用 Node.js 的版本管理器來安裝，比如 nvm。當(dāng)然，也有很多其他的 Node.js 版本管理工具，使用這些工具，我們能很方便地安裝 Node.js，以及在不同的 Node.js 的版本中切換。

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

$ nvm install v8.1.3

安裝完 Node.js 的同時(shí)也會(huì)安裝對(duì)應(yīng)的 npm。

安裝 Git

我們還需要在系統(tǒng)上安裝 Git。如果不確定系統(tǒng)中是否已經(jīng)安裝了 Git，使用下面的命令檢查：

$ git --version

如果出現(xiàn)了 Git 的版本號(hào)，則不需要再安裝了。如果沒有，則需要安裝 Git。

Windows

Windows 系統(tǒng)直接點(diǎn)此連接 https://git-scm.com/download/win 下載 Git 軟件，然后運(yùn)行即可。

macOS

在 macOS 上安裝 Git 有多種不同的方式：

Git installer

Homebrew：運(yùn)行 brew install git

MacPorts：運(yùn)行 sudo port install git +doc +bash_completion +gitweb

我個(gè)人推薦使用 Homebrew 來安裝軟件。當(dāng)然如果你更喜歡 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

如果輸出了一系列的版本號(hào)，說明所有安裝工作都以完成，可以正式使用 hexo 了。

配置

安裝好 hexo 之后，現(xiàn)在我們就可以在 Github 的主分支上來創(chuàng)建我們的文檔了。根據(jù)該文章，你可以：

在一個(gè)已存在的項(xiàng)目中創(chuàng)建文檔

創(chuàng)建一個(gè)新的項(xiàng)目 Create a new repository

簡(jiǎn)單起見，假設(shè)你是新創(chuàng)建了一個(gè)名為 hexo-documentation 的項(xiàng)目，當(dāng)然你也可以用一個(gè)已經(jīng)存在的項(xiàng)目繼續(xù)下面的操作。

接下來使用下面的名令在本地 clone 項(xiàng)目：

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

將 USERNAME 替換為你的用戶名，REPOSITORY 替換為你的項(xiàng)目名稱。例如我執(zhí)行的命令如下：

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

然后使用 cd 進(jìn)入項(xiàng)目目錄，并創(chuàng)建一個(gè)名為 docs 的目錄：

$ cd hexo-documentation
$ mkdir docs

docs 目錄將存放我們的文檔。使用 hexo 初始化 docs 目錄：

$ hexo init docs

上面的命令將生成 hexo 的一些配置并安裝相關(guān)依賴。安裝完成之后，docs 的目錄結(jié)構(gòu)如下：

_config.yml 站點(diǎn)配置文件

package.json Node.js 的依賴文化

scaffolds hexo 發(fā)布文章的時(shí)候使用（本文暫不介紹 hexo 的特性）

source MarkDown 和各種資源文件

themes hexo 的主題

我們可以通過下面的命令來檢查網(wǎng)站是否能夠正常運(yùn)行：

$ hexo generate
$ hexo server

第一個(gè)命令將根據(jù)選用的主題，將 sources 目錄中的文件轉(zhuǎn)換成靜態(tài)網(wǎng)站文件。第二個(gè)命令將啟動(dòng)一個(gè) Web 服務(wù)器，提供這些靜態(tài)網(wǎng)站文件，我們可以通過 http://localhost:4000 來訪問：

目前我們的網(wǎng)站看起來還是一個(gè)博客而不是文檔，不過我們將要將其改成文檔的樣子。

創(chuàng)建一個(gè)主題

要改變網(wǎng)站的外觀，我們需要?jiǎng)?chuàng)建一個(gè) hexo 的主題。主題確定了 hexo 生成的網(wǎng)站的樣式和布局。https://hexo.io/themes/ 這個(gè)網(wǎng)站有很多免費(fèi)的 hexo 主題可以使用。但在這篇文章里，我們要從零開始創(chuàng)建一個(gè) hexo 主題。

Hexo 有一個(gè)名為 landscape 的默認(rèn)主題，在 docs/themes 這個(gè)目錄里面。你可以在 themes 目錄存放多個(gè)主題，但每次只能有一個(gè)主題被使用。接下來讓我們創(chuàng)建自己的主題。在 themes 目錄下創(chuàng)建一個(gè)名為 documentation 的目錄。

Hexo 的主題包含以下文件和目錄：

_config.yml 主題配置文件

languages 國際化的語言包

layout 主題布局，即頁面結(jié)構(gòu)等

scripts 一些 Hexo 插件腳本

source 資源文件夾，里面的文件名以 _ 開頭外的所有文件都會(huì)被當(dāng)作網(wǎng)站的靜態(tài)資源

我們將創(chuàng)建一個(gè)簡(jiǎn)單的靜態(tài)主題，所以我們不需要 scripts 目錄。然后目前僅以中文展示，所以也不需要 languages 目錄。

我們需要做的就是編寫網(wǎng)站的布局，以及一些 CSS 代碼。在本文中我將使Sass 來生成 CSS，但 hexo 并不能直接處理 Sass，但幸運(yùn)的是有 hexo-renderer-sass 這個(gè)插件來幫助 hexo 處理 Sass。

使用 npm 來安裝 hexo-renderer-sass，在 ./docs（注意不是在 themes 目錄里面）運(yùn)行下面的命令：

$ npm install --save hexo-renderer-sass

然后回到 themes 目錄里面，配置 Sass，不然 hexo-renderer-sass 插件不會(huì)被加載。在 docs/themes/documentation/_config.yml 文件中加入下面的代碼：

node_sass:
  outputStyle: nested
  precision: 4
  sourceComments: false

Sass 的所有可配置在 node-sass

接下來就可以編寫 Sass 代碼了。不過在本文中我不會(huì)詳細(xì)介紹怎么寫 Sass 樣式，因?yàn)樗捅疚膬?nèi)容無關(guān)，而且范圍太大，一時(shí)半會(huì)兒寫不完。你可以在這里 https://github.com/nodejh/hexo-documentation 找到這些文件，然后把他們復(fù)制到你的項(xiàng)目中，或者你也可以創(chuàng)建自己的樣式。

讓我們繼續(xù)回到布局，開始編寫代碼之前，還有一個(gè)重要的事情就是選擇模板引擎，如 swig、ejs 等。Hexo 默認(rèn)使用的模版引擎是 swig，這也是我們將要使用的。

接下來創(chuàng)建文件 docs/themes/documentation/layout/post.swig，并寫入下面的代碼：




  
  {{config.title + " - " + page.title}}
  
  
  


  
    
      Documentation
    
    
      {% for section in site.data.nav %}
        
          {{ section.title }}
          
            {% for item in section.items %}
              
                {{item.title}}
              
            {% endfor %}
          
        
      {% endfor %}
    
    
      Project on github
    
  
  
    
      {{page.title}}
      {{page.content}}
    
  
  
    {% if page.prev %}
      Previous
    {% endif %}
    {% if page.next %}
      Next
    {% endif %}

簡(jiǎn)單分析一下代碼。


  
  {{config.title + " - " + page.title}}

頭部主要包括兩部分：

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

links 鏈接里面包括 normalize CSS，使默認(rèn)的樣式保持跨瀏覽器的一致性；Google Fonts，使文本顯示更友好；url_for，這是 Hexo 的一個(gè)輔助函數(shù)，可以在路徑前加上根路徑

接下來看 body 部分，大體上還是 HTML。一些重點(diǎn)部分稍后會(huì)詳細(xì)介紹。


  {% for section in site.data.nav %}
  
    {{ section.title }}
    
      {% for item in section.items %}
        
          
            {{ item.title }}
          
        
      {% endfor %}
    
  
  {% endfor %}

上面的代碼會(huì)生成網(wǎng)站的菜單部分，菜單項(xiàng)來自于 site.data.nav 這個(gè)對(duì)象，稍后我們會(huì)在 docs/source/_data/nav.yml 中創(chuàng)建。source/_data 是 Hexo 的數(shù)據(jù)文件。site.data.nav 即 _data 目錄中的 nav.yml 文件。nav.yml 中是一個(gè)包含 title 和 items 對(duì)象的數(shù)組。

接下來比較重要的是文章內(nèi)容這部分：


  {{ page.title }}
  {{ page.content }}

這里面包括了文章標(biāo)題和內(nèi)容兩部分。文章內(nèi)容是根據(jù) MarkDown 文件生成的 HTML。

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

{% if page.prev %}
  上一頁
{% endif %}
{% if page.next %}
  下一頁
{% endif %}

上面的代碼中，我們假設(shè)每個(gè)頁面都有 “上一頁” 和 “下一頁” 按鈕。

然后創(chuàng)建一個(gè)首頁 documentation/layout/index.swig：




  
  {{config.title + " - " + page.title}}
  
  
  


  
    
      Get Start

現(xiàn)在差不多就完成了！不僅是布局文件完成了，我們的主題也制作好了。最后一件事情就是修改 Hexo 生成靜態(tài)文件的時(shí)候使用的主題。修改 docs/_config.yml 文件中的 theme 屬性：

theme: documentation

所有事情都做完了！接下來我們就可以創(chuàng)建文檔了。

編寫文檔

接下來就到了整篇文章最重要的部分了，為我們的項(xiàng)目編寫文檔。我們將在 docs/source/ 目錄完成這些事情。這里的文檔是網(wǎng)站內(nèi)容的來源，以及網(wǎng)站的菜單。

首先創(chuàng)建菜單。Hexo 提供了讓我們定義一些數(shù)據(jù)文件，并通過 site.data 來訪問。首先在 source 目錄里面創(chuàng)建 _data 目錄，然后創(chuàng)建名為 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 中的文件。

在上面創(chuàng)建的菜單中，我們創(chuàng)建了兩篇文章，每篇文章有兩個(gè)部分。最后我們就只需要?jiǎng)?chuàng)建頁面了。在編寫 MarkDown 之前，先創(chuàng)建以下文件，與菜單對(duì)應(yīng)：

what-is-it.md

how-it-works.md

installation.md

using.md

接下來就要往文件中寫入內(nèi)容。文件的開頭部分是 Front-matter，里面是頁面的一些設(shè)置，F(xiàn)ront-matter 是包含在兩個(gè) --- 之間的 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 中有下面這些設(shè)置：

layout 頁面的布局

id 頁面的唯一標(biāo)識(shí)

title 頁面標(biāo)題

next 下一頁鏈接

按照類似的方法編寫其他幾個(gè) MarkDown 文件。當(dāng)網(wǎng)站創(chuàng)建好之后，這些 MarkDown 內(nèi)容會(huì)被轉(zhuǎn)換為 HTML。

編輯好了之后，就可以生成靜態(tài)網(wǎng)站了：

$ hexo generate
$ hexo server

然后通過 http://localhost:4000 就可以看到如下頁面：

部署到 GitHub Pages

現(xiàn)在我們的文檔網(wǎng)站就全部做好了，接下來需要做的就是將其部署到 Github Pages 上。如果我們手動(dòng)來實(shí)現(xiàn)，就需要?jiǎng)?chuàng)建 gh-pages 分支，生成靜態(tài)網(wǎng)站，復(fù)制網(wǎng)站文件到 gp-pages 分支，commit 并且 push 代碼到 GitHub。當(dāng)修改文檔之后，又得重復(fù)這些工作。

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

$ 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！現(xiàn)在就只剩下一件事情了，就是將網(wǎng)站部署到 Github 上，在終端上運(yùn)行：

$ hexo generate
$ hexo deploy

Hexo 將生成靜態(tài)文件，并將其自動(dòng)部署到 gh-pages 分支上。部署完成之后，我們就可以通過 https://nodejh.github.io/hexo-documentation 來訪問了。

總結(jié)

如果你想要的項(xiàng)目被被人使用，文檔是非常必要的。在 GitHub 上也有很多創(chuàng)建項(xiàng)目文檔的方法。對(duì)于中大型項(xiàng)目來說，維護(hù)一個(gè)文檔網(wǎng)站也是很有必要的。Hexo 不僅能生成靜態(tài)網(wǎng)站，同時(shí)也提供了部署網(wǎng)站的方案，非常方便我們使用。

使用 Hexo 創(chuàng)建項(xiàng)目文檔網(wǎng)站

云服務(wù)器 GPU云服務(wù)器 linux創(chuàng)建文檔 linux項(xiàng)目文檔 php 創(chuàng)建文檔注釋 java項(xiàng)目分析文檔

文章版權(quán)歸作者所有，未經(jīng)允許請(qǐng)勿轉(zhuǎn)載,若此文章存在違規(guī)行為，您可以聯(lián)系管理員刪除。

轉(zhuǎn)載請(qǐng)注明本文地址：http://systransis.cn/yun/50938.html

發(fā)表評(píng)論

登陸后可評(píng)論

0條評(píng)論

mikasa

男|高級(jí)講師

我要關(guān)注我要私信

TA的文章

碼農(nóng)長(zhǎng)壽指南

閱讀 2590·2019-08-30 10:53
前端er怎樣操作剪切復(fù)制以及禁止復(fù)制+破解等

閱讀 3192·2019-08-29 16:20
前端每日實(shí)戰(zhàn)：41# 視頻演示如何創(chuàng)作用純 CSS 繪制一支栩栩如生的鉛筆

閱讀 2948·2019-08-29 15:35
常用CSS布局

閱讀 1770·2019-08-29 12:24
網(wǎng)頁元素CSS居中實(shí)現(xiàn)完整攻略

閱讀 2878·2019-08-28 18:19
Vue 組件通信詳解

閱讀 1854·2019-08-23 18:07
Ant Design UI組件之Select踩坑

閱讀 2335·2019-08-23 15:31
Webpack 熱更新機(jī)制

閱讀 1169·2019-08-23 14:05

成人国产在线小视频_日韩寡妇人妻调教在线播放_色成人www永久在线观看_2018国产精品久久_亚洲欧美高清在线30p_亚洲少妇综合一区_黄色在线播放国产_亚洲另类技巧小说校园_国产主播xx日韩_a级毛片在线免费

資訊專欄INFORMATION COLUMN

上云采購季！| 2核2G4M爆款云服務(wù)器低至59元/年，更有多臺(tái)、長(zhǎng)期優(yōu)惠，快來選購！

使用 Hexo 創(chuàng)建項(xiàng)目文檔網(wǎng)站

{{page.title}}

{{ page.title }}

相關(guān)文章

hexo+css創(chuàng)建自己的blog（搭建）

hexo搭建博客分享

**2017年最新基于hexo搭建個(gè)人免費(fèi)博客——從零開始**

**2017年最新基于hexo搭建個(gè)人免費(fèi)博客——從零開始**

發(fā)表評(píng)論

0條評(píng)論

mikasa

男|高級(jí)講師

TA的文章

碼農(nóng)長(zhǎng)壽指南

前端er怎樣操作剪切復(fù)制以及禁止復(fù)制+破解等

前端每日實(shí)戰(zhàn)：41# 視頻演示如何創(chuàng)作用純 CSS 繪制一支栩栩如生的鉛筆

常用CSS布局

網(wǎng)頁元素CSS居中實(shí)現(xiàn)完整攻略

Vue 組件通信詳解

Ant Design UI組件之Select踩坑

Webpack 熱更新機(jī)制

最新活動(dòng)

資訊專欄INFORMATION COLUMN

上云采購季！| 2核2G4M爆款云服務(wù)器低至59元/年，更有多臺(tái)、長(zhǎng)期優(yōu)惠，快來選購！

使用 Hexo 創(chuàng)建項(xiàng)目文檔網(wǎng)站

{{page.title}}

{{ page.title }}

相關(guān)文章

發(fā)表評(píng)論

0條評(píng)論

男|高級(jí)講師

TA的文章

最新活動(dòng)

上云采購季！| 2核2G4M爆款云服務(wù)器低至59元/年，更有多臺(tái)、長(zhǎng)期優(yōu)惠，快來選購！