使用 Hexo 創建項目文檔網站

mikasa 發布于2019-08-01 17:05 / 703人閱讀

摘要：而且通常來說，是用來介紹項目，而不是展示文檔。如果不確定系統中是否已經安裝了，使用下面的命令檢查如果出現了的版本號，則不需要再安裝了。例如我執行的命令如下然后使用進入項目目錄，并創建一個名為的目錄目錄將存放我們的文檔。

當我們發布一個開源項目的時候，最重要的事情之一就是要創建項目文檔。對使用項目的用戶來說，文檔是非常有必要的，通常我們可以使用下面這些方式來創建文檔：

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

第一個命令將根據選用的主題，將 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，并寫入下面的代碼：




  
  {{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 %}

簡單分析一下代碼。


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

頭部主要包括兩部分：

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

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

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


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

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

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


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

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

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

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

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

然后創建一個首頁 documentation/layout/index.swig：




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


  
    
      Get Start

現在差不多就完成了！不僅是布局文件完成了，我們的主題也制作好了。最后一件事情就是修改 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 創建項目文檔網站

GPU云服務器云服務器 linux創建文檔 linux項目文檔 php 創建文檔注釋 java項目分析文檔

文章版權歸作者所有，未經允許請勿轉載,若此文章存在違規行為，您可以聯系管理員刪除。

轉載請注明本文地址：http://specialneedsforspecialkids.com/yun/50938.html

hexo+css創建自己的blog（搭建）

摘要：目前比較火的和的文檔都是使用框架實現的。二的安裝安裝前，確保電腦中已經安裝了和。可以參照來自定義日期格式。值為時禁用主題部署參考部署部分的配置五部署上部署安裝中配置部署部分的設置終端進入目錄運行一、什么是hexo Hexo是一個快速、簡潔且高效的博客框架，使用Markdown（或其他渲染引擎）解析文章，在幾秒內，即可利用靚麗的主題生成靜態網頁。目前比較火的vue和weex的文檔都是使...

phoenixsky 2019-08-29 13:20 評論0 收藏0
hexo搭建博客分享

摘要：在這里的作用只要是用管理員權限安裝一些軟件和開啟一些服務創建操作用戶和分配權限。輸入完畢之后，命令模式下輸入強制保存退出。保存之后，修改文件權限最后一步，開放服務器中的端口。知識點準備我主要參考了兩篇文章: 【持續更新】最全Hexo博客搭建+主題優化+插件配置+常用操作+錯誤分析基于CentOS搭建Hexo博客我采用的方案是云服務器+域名的方式首先是要搞懂一些概念 Ngi...

psychola 2019-08-23 18:18 評論0 收藏0
2017年最新基于hexo搭建個人免費博客——從零開始

摘要：前言搭建此博客是因為通過上了解到進而知道了可以把靜態網頁博客托管給倉庫或許您已經通搭建個人博客網站了解到如何通過實現個人博客網站的建立。但是盡管您已經成功建立博客網站，但是你需要對網站做合適的配置和調整才能迎合你的網站要求。 showImg(https://segmentfault.com/img/remote/1460000008725509?w=1449&h=459); 前言搭建...

Paul_King 2019-08-29 12:14 評論0 收藏0
2017年最新基于hexo搭建個人免費博客——從零開始

摘要：前言搭建此博客是因為通過上了解到進而知道了可以把靜態網頁博客托管給倉庫或許您已經通搭建個人博客網站了解到如何通過實現個人博客網站的建立。但是盡管您已經成功建立博客網站，但是你需要對網站做合適的配置和調整才能迎合你的網站要求。 showImg(https://segmentfault.com/img/remote/1460000008725509?w=1449&h=459); 前言搭建...

zacklee 2019-08-20 15:12 評論0 收藏0