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

時間 2019-11-17

原文原文鏈接

tags: docsify doc githubjavascript

1.引言

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

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

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

2.docsify簡介

按docsify官網的介紹，一句話:一個神奇的文檔網站生成工具，使用它，可使用簡單的方式，構建一個專業的文檔網站。若是使用過GitBook和Hexo的同窗，能夠知識它們使用markdown編寫文檔，而後轉爲html進行顯示。而docsify 是一個動態生成文檔網站的工具。不一樣於 GitBook、Hexo 的地方是它不會生成將 .md 轉成 .html 文件，全部轉換工做都是在運行時進行。只須要建立一個 index.html ，就能夠開始寫文檔並且直接部署在 GitHub Pages進行發佈，方便、快捷、格式友好，樣式不錯。vue

3. 使用docsify構建文檔

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

3.1 構建docsify目錄結構

3.1.1 目錄結構

docsify有其規範的目錄結構，建立一個目錄，如test，目錄下最基本的結構以下：node

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

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

3.1.2 編寫`index.html`

index.htmlnginx

<!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" href="//unpkg.com/docsify/themes/vue.css">
</head>
<body>
  <div id="app"></div>
  <script> window.$docsify = { //... } </script>
  <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
</body>
</html>

複製代碼

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

3.1.3 編寫`README.MD`

文檔內容均以markdown的方式編寫，README.MD做爲文檔的首頁，以下是README.MD的內容github

## 我是首頁

這是個人首頁介紹
複製代碼

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="//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="//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="//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" href="//unpkg.com/docsify/themes/vue.css">
<link rel="stylesheet" href="//unpkg.com/docsify/themes/buble.css">
<link rel="stylesheet" href="//unpkg.com/docsify/themes/dark.css">
<link rel="stylesheet" href="//unpkg.com/docsify/themes/pure.css">
<link rel="stylesheet" href="//unpkg.com/docsify/themes/dolphin.css">
複製代碼

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

#示例地址：
https://jhildenbiddle.github.io/docsify-themeable/#/customization
#引入方法：
link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple.css">
複製代碼

3.6 添加搜索功能

通常文章提供搜索功能是比較人性化的功能，在docsify中添加搜索功能，只須要在index.html添加search插件，而後在window.$docsify添加search參數便可。以下：

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

具體參數設置可參考官網

添加搜索功能後，效果以下：

4. 總結

本篇文章介紹了docsify的優勢，並對使用docsify構建文檔網站的步驟進行說明，分別是：引入docsify文件 -> 設置目錄框架 -> 編寫markdown內容 -> 設置封面/樣式 -> 添加搜索功能。而後使用python啓動（固然也可使用其它web服務器如nginx,apache）提供靜態網站服務便可。但願對有須要的同窗有所幫助。