使用docsify構建專業文檔網站(上)

tags: docsify doc github

1.引言

在軟件開發過程中，編程人員經常需要寫文檔，如開發文檔、接口文檔、使用手冊等，也會經常編寫blog記錄開發過程，技術感悟。對于這些文檔，一般情況下編寫人員有以下幾種需求：編寫簡單、對外發布、格式友好、形式專業。而編寫的工具則有好多，包括以下幾類：

  • word工具類：如office word，wps,txt等
  • 平臺博客類：csdn，簡書，oschina等
  • 自建網站類：github，hexo，gitbook，markdown等
  • 知識工具類：confluence，語雀，看云等

當然，各種工具有各自的優缺點，簡單一點的話，使用語雀、看云來寫長系列文章或者書籍也比較適合，但作為一個開發人員，希望找一個能屬于自己的，簡單的，有點逼格的文檔工具，特別是針對開源軟件文檔編寫，放個pdf或者doc文檔，不便于維護，格調也不夠高，最好能跟github關聯，即時可看，又方便維護，如此，則非docsify莫屬了（當然gitboot也行）。如下可以截圖看一下基于docsify構建的文檔。本文針對如何使用docsify實現文檔構建進行講解，希望能幫助到想構建自己的文檔網站的同學。

docsify官網
另一種樣式

2.docsify簡介

按docsify官網的介紹，一句話:一個神奇的文檔網站生成工具，使用它，可以使用簡單的方式，構建一個專業的文檔網站。如果使用過GitBook和Hexo的同學，可以知識它們使用markdown編寫文檔，然后轉為html進行顯示。而docsify 是一個動態生成文檔網站的工具。不同于 GitBook、Hexo 的地方是它不會生成將 .md 轉成 .html 文件，所有轉換工作都是在運行時進行。只需要創建一個 index.html ，就可以開始寫文檔而且直接部署在 GitHub Pages進行發布，方便、快捷、格式友好，樣式不錯。

3. 使用docsify構建文檔

本章節將對如何使用docsify構建文檔進行詳細描述。

3.1 構建docsify目錄結構

3.1.1 目錄結構

docsify有其規范的目錄結構，創建一個目錄，如test，目錄下最基本的結構如下：

  • index.html ： 入口文件
  • README.md ： 會做為主頁內容渲染
  • .nojekyll ： 用于阻止 GitHub Pages 會忽略掉下劃線開頭的文件

若在本地測試，.nojekyll可不需要，若發布到Github Pages，則需要此文件。

3.1.2 編寫index.html

index.html

<!DOCTYPE html>
<html>
<head>
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
  <meta name="viewport" content="width=device-width,initial-scale=1">
  <meta charset="UTF-8">
  <link rel="stylesheet" >
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      //...
    }
  </script>
  <script src="http://unpkg.com/docsify/lib/docsify.min.js"></script>
</body>
</html>

注意
此處使用在線引入docsify的js，如//unpkg.com/docsify/lib/docsify.min.js，用戶也可以直接下載此文件到本地，進行本地引用。

3.1.3 編寫README.MD

文檔內容均以markdown的方式編寫，README.MD作為文檔的首頁，如下是README.MD的內容

## 我是首頁

這是我的首頁介紹

3.1.4 修改logding提示

初始化時會顯示 Loading... 內容，可以自定義提示信息。修改index.html的app的div中的文字即可，如下：

<div id="app">加載中...</div>

3.1.5 本地預覽網站

最方便的就是本地安裝一個python(不會安裝的請百度)，然后使用Python來啟動一個服務，對于python3，在此目錄下運行以下命令即可啟動：

python -m http.server 3000

3000是開啟的端口號，用戶可自行定義，啟動后，出現以下提示：
Serving HTTP on 0.0.0.0 port 3000 (http://0.0.0.0:3000/) ...則表示啟動成功。使用瀏覽器訪問localhost:3000即可訪問文檔。如下：

本地運行

至此，已經完成最基本的文檔網站了，若是把完整的文檔寫在README.MD中，文檔也基本完成了，可以正常顯示。修改文檔和index.html后，刷新頁面即可顯示更新。

3.1.6 使用docsify-cli創建

若已安裝nodejs，則可以不手動創建上面的文件，使用npm安裝docsify-cli，創建目錄，然后使用docsify init ./，它完成的工作與前面手動生成的文件是一致的。具體可參考官方文檔。

3.2 設置文檔側邊欄

如前面示例，默認情況下，文檔側邊欄會根據當前文檔的標題生成目錄，且會把目錄全部展開。如下所示：


默認側邊欄

但一般我們寫文檔或書籍，都習慣把長文檔分章節編寫（即每章節一個文件），然后顯示時目錄可折疊，更方便閱讀。docsify則提供了多文檔側邊欄的定制。

3.2.1 設置多文檔側邊欄

假設文檔結構（書結構）如下：

版權信息
序
第一篇
  -- 第1章
    -- 1.1 xxx
    -- 1.2 xxx
  -- 第2章
第二篇
  ...

對應的文件如下（注意：由于docsify是根據路徑作為url訪問的，目錄名及文件名不要使用中文或空格）：

.
├── a
│   ├── 1.md
│   └── 2.md
├── b
├── copyright.md
├── index.html
├── preface.md
└── README.md

只需要兩步即可完成側邊欄設置：

  • (1) 在index.html文件中的window.$docsify添加loadSidebar: true,選項：
<script>
  window.$docsify = {
    loadSidebar: true
  }
</script>
<script src="http://unpkg.com/docsify"></script>
  • (2) 根目錄創建_sidebar.md文件

編寫目錄內容，有鏈接內容則使用[xx](yy)格式，xx是顯示內容，yy是連接地址，連接地址以index.html所在目錄為當前目錄，連接到對應文件的路徑，文件后綴md省略。有層次結構的使用空格分隔層次。如下：

* [版權信息](copyright)
* [序](preface)
* 第一篇
  * [第1章](a/1)
  * [第2章](a/2)
* 第二篇
  * [第3章](b/3)

設置完成后，刷新頁面，顯示結果如下：


設置側邊欄

3.2.2 設置章節目錄顯示

上述定制的側邊欄僅根據_sidebar.md文件顯示了頁面大框架的鏈接，但各章節所在的目錄(標題)沒有顯示，需要在index.html文件中的window.$docsify添加subMaxLevel字段來設置：

<script>
  window.$docsify = {
    loadSidebar: true,
    subMaxLevel: 3
  }
</script>
<script src="http://unpkg.com/docsify"></script>

設置后，效果如下：

設置頁面目錄顯示

注意：subMaxLevel類型是number(數字)，表示顯示的目錄層級
如果md文件中的第一個標題是一級標題，那么不會顯示在側邊欄，如上圖所示

3.2.3 忽略頁面標題在側邊欄目錄顯示

注意： 如果md文件的第一個標題是一級標題，那么默認已經忽略了。

當設置了 subMaxLevel 時，默認情況下每個標題都會自動添加到目錄中。如果你想忽略特定的標題，可以給它添加 {docsify-ignore} ：

# Getting Started

## Header {docsify-ignore}

該標題不會出現在側邊欄的目錄中。

要忽略特定頁面上的所有標題，你可以在頁面的第一個標題上使用{docsify-ignore-all} :

# Getting Started {docsify-ignore-all}

## Header

該頁面所有標題都不會出現在側邊欄的目錄中。

3.3 設置封面

docsify默認是沒有封面的，默認有個首頁./README.md。通過設置coverpage參數，可以開啟渲染封面的功能。

首先需要在index.html文件中的window.$docsify添加coverpage: true選項：

<script>
  window.$docsify = {
    coverpage: true
  }
</script>
<script src="http://unpkg.com/docsify"></script>

接著在項目根目錄創建_coverpage.md文件，內容格式如下：

![logo](_media/icon.svg)
# 我的文檔網站
## 個人文檔網站
> 一個神奇的文檔網站生成鞏固

* Simple and lightweight (~12kb gzipped)
* Multiple themes
* Not build static html files

[GitHub](https://github.com/docsifyjs/docsify/)
[Get Started](#quick-start)
[Get Started](#quick-start)

目前的背景是隨機生成的漸變色，每次刷新都會顯示不同的顏色。docsify封面支持自定義背景色或者背景圖，在_coverpage.md文檔末尾添加：

<!-- 背景圖片 -->
![](_media/bg.png)

<!-- 背景色 -->
![color](#fbb30b)

注意：
1.自定義背景配置一定要在_coverpage.md文檔末尾。
2.背景圖片和背景色只能有一個生效.
3.背景色一定要是#fbb30b這種格式的。
4.icon.svg和bg.png需要自己創建并放到_media目錄下

設置封面后，效果如下：


封面

3.4 編寫markdown內容

如上述示例，文本內容都是使用markdown進行編寫，關于markdown的編寫規范，可參考官方文檔。markdown的編寫工具有很多，熟練的可以直接使用文本進行編輯，中文的markdown工具有Typora，cmdMarkdown，有道云筆記等等。

3.5 選擇主題樣式

docsify默認提供了不同的主題樣式，默認是vue.css。用戶可以根據自己需要來使用即可。

<link rel="stylesheet" >
<link rel="stylesheet" >
<link rel="stylesheet" >
<link rel="stylesheet" >
<link rel="stylesheet" >

還有一些第三方的主題樣式，如：

#示例地址：
https://jhildenbiddle.github.io/docsify-themeable/#/customization
#引入方法：
link rel="stylesheet" >

3.6 添加搜索功能

一般文章提供搜索功能是比較人性化的功能，在docsify中添加搜索功能，只需要在index.html添加search插件，然后在window.$docsify添加search參數即可。如下：

window.$docsify = {
        search: {
            maxAge: 86400000, // 過期時間，單位毫秒，默認一天
            noData: '找不到結果',//搜索不到結果時顯示
            paths: 'auto',//自動
            placeholder: '搜索',//搜索框提示
        },
    }
<script src="http://unpkg.com/docsify/lib/plugins/search.js"></script>

具體參數設置可參考官網

添加搜索功能后，效果如下：

搜索功能

4. 總結

本篇文章介紹了docsify的優點，并對使用docsify構建文檔網站的步驟進行說明，分別是：引入docsify文件 -> 設置目錄框架 -> 編寫markdown內容 -> 設置封面/樣式 -> 添加搜索功能。然后使用python啟動（當然也可以使用其它web服務器如nginx,apache）提供靜態網站服務即可。希望對有需要的同學有所幫助。

5.參考資料

最后編輯于 ：
?著作權歸作者所有,轉載或內容合作請聯系作者
平臺聲明：文章內容（如有圖片或視頻亦包括在內）由作者上傳并發布，文章內容僅代表作者本人觀點，簡書系信息發布平臺，僅提供信息存儲服務。

推薦閱讀更多精彩內容