本文首發於 Nebula Graph Community 公眾號

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

為什麼需要文件

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

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

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

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

文件的需求

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

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

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

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

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

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

打造文件中心

下面來講解下 Nebula 內容與文件團隊是如何使用 MkDocs 和 GitHub 搭建文件中心的。在閱讀本文的同時，可以從 Nebula Graph 文件中心（連結：

MkDocs

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

Mkdocs 支援：

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

Material for MkDocs

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

Material for MkDocs 的安裝和基礎使用方式參考 Material 官方文件。

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

部署文件中心

我們使用 GitHub Pages 和 GitHub Actions 將 GitHub 文件庫部署到文件中心，並實現修改文件後頁面自動更新。

GitHub Pages 預設使用的域名為 {<user> | <organization>}.github.io，我們使用了自定義域名。

設定基本功能

設定網站基本資訊

設定基本資訊需要使用的 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 引數設定成功後，每篇文件的如下位置會出現編輯按鈕，用於修改單篇文件非常方便。

設定導航欄

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
      - ...

顯示效果如下：

豐富文件中心功能

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

應用 Material 主題

在 mkdocs.yml 檔案中加入以下配置：

theme:
  name: material

並在 requirements.txt 檔案中加入一行，內容為 mkdocs-material。這樣就應用了 Material 主題的基本樣式：

設定站點語言

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

除此以外，還可以自定義顏色。

自定義 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 做版本管理。

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。
   2. 修改新分支中的 /mkdocs.yml 檔案，需修改的欄位參考示例 commit。其中 palette 部分為主題顏色，詳細說明參考本文##更改頁面顏色##部分。
   3. 修改上個版本對應分支中的 /.github/workflows/deploy.yaml 檔案，將 run 欄位下的 mike set-default x.x.x -p --rebase 行刪除，以取消老版本的重定向。詳情參考示例 commit。
4. 刪除新分支的 overrides/partials/header.html 檔案，取消頂部通知欄檔案。該檔案會影響 PDF 的生成，因此僅在 master 版本保留，用於告知讀者 master 版本是開發版本，並指向最新的釋出版本。
5. 在 GitHub [Actions] 頁面檢視最後一個 Action，檢查 Mike Deploy xxx 部署，如有斷鏈等報錯即時解決。將非斷鏈但暫時不適合釋出的檔案設定在 /mkdocs.yml 中的 exclude 欄位，這樣能起到隱藏效果，詳細說明參考註釋。
6. 修改前一個版本的前言，建議使用者升級新版本。參考示例。

版本號自動變更

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

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

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

extra:
  nebula:
    release: 2.6.2

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

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

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

以上，為 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

交流圖資料庫技術？加入 Nebula 交流群請先填寫下你的 Nebula 名片，Nebula 小助手會拉你進群~~