> 本文首發於 **[Nebula Graph Community 公眾號](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/WeChatOffical.png)**

![如何打造多版本文件中心](https://www-cdn.nebula-graph.com.cn/nebula-blog/buildi-your-own-docs-website.jpg)

世界上沒有完美的產品，每個不完美的產品都需要一份文件。

## 為什麼需要文件

打造出一款產品後，我們需要一份文件來回答以下問題：

* 設計這款產品的原因是什麼（Why）
* 這是一款什麼樣的產品（What）
* 產品面向的使用者是誰（Who）
* 在哪些場景下可以用這款產品（Where&When）
* 怎樣使用（How）
* 產品的使用限制與其它需要注意的問題（Notes and limitations）
* ……

透過文件介紹這些資訊，新讀者才能更直觀地瞭解產品，決定是否要用它，而產品的使用者則能更順利地使用它。

Nebula Graph也是這樣一款不完美的產品。因此我們需要文件，更需要一個文件中心來集中儲存並有序排列文件，供讀者閱讀和查詢。

## 文件的需求

在最開始的時候，我們的第一位文件工程師@Amber只有一個需求，那就是搭建一個英文文件網站。然而很快她就發現這可不僅僅是一個需求。

![如何打造多版本文件中心](https://www-cdn.nebula-graph.com.cn/nebula-blog/build-your-own-docs-website-01.jpeg)

經過初步分析，我們至少需要做以下事情：

* 確定用什麼寫文件
* 找個地方存放文件檔案
* 讓讀者可以方便地閱讀文件

隨著時間的推移和進一步思考，可達鴨發現了更多需求：

* P0：
    * 有中英文文件網站
    * 文件變更後自動釋出
* P1：
    * 文件版本分離
    * 內容搜尋
* P2：
    * 斷鏈檢查
    * 生成 PDF
* P3：
    * 複用
    * 隱藏
* 等等……

於是，可達鴨開始了打造文件中心的探索之路。

## 打造文件中心

下面來講解下 Nebula 內容與文件團隊是如何使用 MkDocs 和 GitHub 搭建文件中心的。在閱讀本文的同時，可以從 Nebula Graph 文件中心（連結：[https://docs.nebula-graph.com.cn/3.0.1/](https://docs.nebula-graph.com.cn/3.0.1/)）和 GitHub 庫（連結：[https://github.com/vesoft-inc/nebula-docs-cn](https://github.com/vesoft-inc/nebula-docs-cn)）檢視相應的程式碼和效果示例。

### MkDocs

MkDocs 是一個快速、簡單、美觀的開源靜態網站生成器，用於構建專案文件。文件原始檔為 Markdown 格式，配置寫在 YAML 檔案中。

Mkdocs 支援：

* 多主題，每種主題有不同的功能。
* 自定義功能。
* 預覽網站。

### Material for MkDocs

Material for MkDocs 是最流行的 MkDocs 主題之一，支援透過 Python、Docker、Git 等方式安裝。Nebula Graph 文件中心有若干功能由該主題提供。

Material for MkDocs 的安裝和基礎使用方式參考 [Material 官方文件](https://squidfunk.github.io/mkdocs-material/getting-started/#installation)。

> 說明：無需單獨安裝 MkDocs，Material 會將其一起安裝。

### 部署文件中心

我們使用 [GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages) 和 [GitHub Actions](https://squidfunk.github.io/mkdocs-material/publishing-your-site/#with-github-actions) 將 GitHub 文件庫部署到文件中心，並實現修改文件後頁面自動更新。

GitHub Pages 預設使用的域名為 `{<user> | <organization>}.github.io`，我們使用了[自定義域名](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/about-custom-domains-and-github-pages)。

### 設定基本功能

#### 設定網站基本資訊

設定基本資訊需要使用的 `mkdocs.yml` 配置如下：

```
# 網站名稱
site_name: Nebula Graph Database 手冊
# 網站描述
site_description: Documentation for Nebula Graph Database
# 作者資訊
site_author: Nebula Graph
# 網站（文件中心）的連結
site_url: https://docs.nebula-graph.com.cn/master/
# 版權資訊
copyright: Copyright © 2021 Nebula Graph - 浙ICP備20010487號
```

#### 設定 GitHub 資訊

Nebula 文件庫託管在 GitHub 上，因此需要在 `mkdocs.yml` 中設定 GitHub 相關資訊。

```
# GitHub庫的名稱
repo_name: 'vesoft-inc/nebula-docs-cn'
# GitHub庫的連結
repo_url: 'https://github.com/vesoft-inc/nebula-docs-cn'
# 新增正確的路徑後文件右上角會出現編輯按鈕，點選可直接跳轉到編輯檔案的頁面
edit_uri: 'edit/master/docs-2.0/'
# 指定包含文件源Markdown檔案的目錄
docs_dir: docs-2.0
edit_uri 引數設定成功後，每篇文件的如下位置會出現編輯按鈕，用於修改單篇文件非常方便。
```

![如何打造多版本文件中心](https://www-cdn.nebula-graph.com.cn/nebula-blog/build-your-own-docs-website-02.png)

#### 設定導航欄

Markdown 檔案在導航欄的顯示順序可以透過 `mkdocs.yml` 檔案中的 `nav` 欄位配置。格式示例如下：
```
nav:
  - 前言: README.md
  - 簡介:
      - 什麼是 Nebula Graph: 1.introduction/1.what-is-nebula-graph.md
      - 資料模型: 1.introduction/2.data-model.md
      - ...
      - 服務架構:
        - 架構總覽: 1.introduction/3.nebula-graph-architecture/1.architecture-overview.md
        - ...
 
  - 快速入門:
      - 快速入門流程: 2.quick-start/1.quick-start-workflow.md
      - 步驟1：安裝 Nebula Graph: 2.quick-start/2.install-nebula-graph.md
      - ...
```
顯示效果如下：

![如何打造多版本文件中心](https://www-cdn.nebula-graph.com.cn/nebula-blog/build-your-own-docs-website-03.png)

#### 豐富文件中心功能

剛剛部署的文件中心僅有類似下圖的預設的頁面樣式，我們需要挑選配置項和外掛實現更多功能。

![如何打造多版本文件中心](https://www-cdn.nebula-graph.com.cn/nebula-blog/build-your-own-docs-website-04.png)

#### 應用 Material 主題

在 `mkdocs.yml` 檔案中加入以下配置：
```
theme:
  name: material
```
並在 `requirements.txt` 檔案中加入一行，內容為 mkdocs-material。這樣就應用了 Material 主題的基本樣式：

![如何打造多版本文件中心](https://www-cdn.nebula-graph.com.cn/nebula-blog/build-your-own-docs-website-05.png)

#### 設定站點語言

Material for MkDocs 支援多種語言。例如，如果是中文文件，做如下設定：
```
theme:
  language: 'zh'
```

#### 更改頁面顏色

Material for MkDocs 提供了兩類顏色主題，淺色背景的 default 和深色背景的 slate。編輯 `mkdocs.yml` 檔案，加入 palette 欄位：
```
theme:
  name: material
  palette:
    scheme: default
```

#### 切換頁面主題

我們可以在深色和淺色主題之間切換，實現日間模式和夜間模式的效果。編輯 mkdocs.yml 檔案，修改 palette 欄位：
```
palette:
    - scheme: default
      primary: cyan
      accent: cyan
      toggle:
        icon: material/toggle-switch-off-outline
        name: Switch to dark mode
    - scheme: slate
      primary: deep orange
      accent: deep orange
      toggle:
        icon: material/toggle-switch
        name: Switch to light mode
```
除此以外，還可以[自定義顏色](https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#custom-colors)。

#### 自定義 logo

可以使用文件庫內的各型別圖片，包括但不限於 PNG、SVG 格式，或者外部網路上的圖片，作為頁面 logo。這樣編輯 `mkdocs.yml` 檔案：
```
theme:
  logo: assets/logo.png
```
如果是外鏈，直接在 `logo:` 後面設定連結即可。

#### 關於搜尋

Material for MkDocs 內建了頁面搜尋功能，這樣編輯 `mkdocs.yml` 檔案即可使用：
```
plugins:
  - search
```
但是，該搜尋功能對中文和英文混合的場景的支援有很多問題，我們也還在尋找方案。

#### 設定社交主頁連結

Nebula Graph 是在 GitHub 開源的產品，因此文件中心設定了 GitHub 主頁的 logo 和連結，方式如下：
```
  social:
    - icon: 'fontawesome/brands/github'
      link: 'https://github.com/vesoft-inc/nebula-docs-cn'
```

#### 設定標題行自動隱藏

為了不讓標題行遮擋內容，最佳化閱讀體驗，我們設定了讓標題行在頁面下滑後自動隱藏。
```
theme:
  features:
    - header.autohide
```

### 版本分離

版本分離是 Nebula 文件中心的關鍵功能之一。開源開發的 Nebula Graph 迭代快，每個版本的特性都有區別，因此文件也根據產品功能分為不同版本。

#### 版本管理

我們使用 [mike](https://github.com/jimporter/mike) 做版本管理。

mike 的使用方式如下：

1. 在 requirements.txt 檔案中加入一行，內容為：mike

2. 在 `mkdocs.yml` 中設定：

```
  version:
    method: mike
```

3. 在 `/.github/workflows/deploy.yaml` 中設定：

```
jobs:
  deploy:
    steps:
      - name: Mike Deploy master
        run: |
# 指定要部署的版本
          mike deploy 2.5.1 -p --rebase
# 指定文件中心預設跳轉的版本，同時在歷史版本中刪除這句話。
          mike set-default 2.5.1 -p --rebase
```

#### 版本釋出

Nebula Graph 文件的版本與核心版本保持一致，釋出文件新版本的方式如下：

1. 在 master 分支完成新版本文件開發，將相關 PR 合併。
2. 建立新的 GitHub 分支。
    1. 在文件的 GitHub 主頁，點選分支切換按鈕。
    2. 在 `Find or create a branch...` 文字框中輸入新版本的名稱，例如 v2.6.0。
    3. 點選下拉選單底部（倒數第二行）的 Create brach: xxx from master 。
3. 修改配置檔案。
    1. 修改新分支中的 `/.github/workflows/deploy.yaml` 檔案，需修改的欄位參考[示例 commit](https://github.com/vesoft-inc/nebula-docs-cn/commit/a09d50c7447ab02f5101ac811deeff16829c5db3#diff-98d0f806abc9af24e6a7c545d3d77e8f9ad57643e27211d7a7b896113e420ed2)。
    2. 修改新分支中的 /mkdocs.yml 檔案，需修改的欄位參考[示例 commit](https://github.com/vesoft-inc/nebula-docs-cn/commit/a09d50c7447ab02f5101ac811deeff16829c5db3#diff-98d0f806abc9af24e6a7c545d3d77e8f9ad57643e27211d7a7b896113e420ed2)。其中 palette 部分為主題顏色，詳細說明參考本文##更改頁面顏色##部分。
    3. 修改上個版本對應分支中的 `/.github/workflows/deploy.yaml` 檔案，將 run 欄位下的 `mike set-default x.x.x -p --rebase` 行刪除，以取消老版本的重定向。詳情參考[示例 commit](https://github.com/vesoft-inc/nebula-docs-cn/commit/4bfb3f29291adaf307772498d01d30cbc15e796f)。
4. 刪除新分支的 `overrides/partials/header.html` 檔案，取消頂部通知欄檔案。該檔案會影響 PDF 的生成，因此僅在 master 版本保留，用於告知讀者 master 版本是開發版本，並指向最新的釋出版本。
5. 在 GitHub [Actions] 頁面檢視最後一個 Action，檢查 Mike Deploy xxx 部署，如有斷鏈等報錯即時解決。將非斷鏈但暫時不適合釋出的檔案設定在 /mkdocs.yml 中的 [exclude 欄位](https://github.com/vesoft-inc/nebula-docs-cn/blob/master/mkdocs.yml#L505)，這樣能起到隱藏效果，詳細說明參考註釋。
6. 修改前一個版本的前言，建議使用者升級新版本。參考[示例](https://github.com/vesoft-inc/nebula-docs-cn/commit/3a0afee231f7692451463ceb672acad20d303fbd#diff-0b80360ed703766905bd5f8a59e4434a6fc05090e62dcba37e35021e0a3fbf6d)。

#### 版本號自動變更

文件中的版本號有時需要根據版本修改，使用 macros 外掛設定宏變數後，只要修改了 mkdocs.yml 檔案中的設定，就可以方便地實現文件中的版本號自動變更。macros 的設定步驟如下：

1. 在 `requirements.txt` 檔案中加入一行，內容為：`mkdocs-macros-plugin`

2.在 `mkdocs.yml` 中的 `extra` 欄位設定版本號的 macros 鍵值對，示例如下：
```
extra:
  nebula:
    release: 2.6.2
```

設定後，在 Markdown 程式碼中使用 \{\{<key>.<value>\}\} 的形式即可生成相應的版本號。進行了上述設定後，\{\{nebula.release\}\} 即代表 2.6.1。

原始碼和顯示效果的對比如下：

![如何打造多版本文件中心](https://www-cdn.nebula-graph.com.cn/nebula-blog/build-your-own-docs-website-06.png)

這其實也是短語級別的內容複用。

以上，為 Nebula 內容與文件團隊文件搭建實踐。

當然我們還有一些內容並未在本文展示，下面內容將在後面的文章中娓娓道來：

* mkdocs_latest_release_plugin
* mkdocs-git-revision-date-localized-plugin
* note
* mdx_truly_sane_lists
* pymdownx.superfences
* pymdownx.snippets
* pymdownx.arithmatex
* exclude
* mkdocs-with-pdf
* pydown-snippets
* Action 錯誤排查
* 關於中文的特殊處理 [https://github.com/vesoft-inc/nebula-docs-cn/blob/master/pkglist.txt](https://github.com/vesoft-inc/nebula-docs-cn/blob/master/pkglist.txt)

交流圖資料庫技術？加入 Nebula 交流群請先[填寫下你的 Nebula 名片](https://wj.qq.com/s2/8321168/8e2f/)，Nebula 小助手會拉你進群~~</value></key></organization></user>

Nebula Graph｜如何打造多版本文件中心

相關文章