使用開源文件工具docsify，用寫部落格的姿勢寫文件

throwable發表於2020-09-03

前提

下面的簡介摘抄自docsify的官網 https://docsify.js.org 中的簡介

docsify是一個神奇的文件網站生成器。他可以快速幫你生成文件網站。不同於GitBook、Hexo的地方是它不會生成靜態的.html檔案，所有轉換工作都是在執行時。如果你想要開始使用他，只需要建立一個index.html就可以開始編寫文件並直接部署在GitHub Pages（碼雲Pages、阿某雲OSS或者鵝雲COS等等）。它的主要特性如下：

無需構建，寫完文件直接釋出（執行時markdown文件轉換）
容易使用並且輕量（壓縮後 ~21kB，當然這裡不包括markdown文件的大小）
智慧的全文搜尋
豐富的API
支援Emoji，可以在文中新增表情
相容IE11
支援服務端渲染SSR

docsify的最大優勢是可以讓使用者感受到用寫部落格的姿勢去編寫文件，反過來說也行：用寫文件的姿勢去寫部落格。docsify的學習成本很低，部署簡單，官方文件十分完善，原則上只需要理解markdown的語法和Node.js的安裝即可，對於非IT技術從業者也十分友好。知名的技術公眾號號主JavaGuide的站點就是採用docsify構建的。下文簡單介紹docsify的使用姿勢。

安裝docsify和初始化專案

docsify是一個Node.js外掛，所以需要提前安裝Node.js。安裝完畢後，通過下面命令全域性安裝docsify：

npm i docsify-cli -g

假設磁碟中有一個/docsify-demo目錄，在該目錄下可以直接通過docsify init命令初始化專案：

# 先進入docsify-sample目錄，在docsify-sample目錄開啟命令列
docsify init

命令執行成功後，會在專案的目錄生成三個新的檔案如下：

index.html為入口檔案，css、js以及配置項都在此檔案中修改。
README.md會作為預設主頁內容渲染。
.nojekyll用於阻止GitHub Pages忽略掉下劃線開頭的檔案。

接著呼叫docsify serve命令然後訪問http://localhost:3000即可進行本地預覽，效果如下：

下面在簡單介紹docsify的功能使用的時候，全部使用預設的配置引數，其實一般情況下，不太建議進行預設配置項的修改。

docsify的配置項修改或者靜態資源增添基本都在index.html檔案中操作，而其他markdown檔案（包括內建的側邊欄、封面檔案和自己新增的文章）都是執行時載入和渲染的。

基本配置

一份基本的配置項如下：

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <title>神奇的docsify</title>
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
    <!-- 設定瀏覽器圖示 -->
    <link rel="icon" href="/favicon.ico" type="image/x-icon" />
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon" />
    <meta name="description" content="Description">
    <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
    <!-- 預設主題 -->
    <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css">
</head>

<body>
    <!-- 定義載入時候的動作 -->
    <div id="app">載入中...</div>
    <script>
        window.$docsify = {
            // 專案名稱
            name: 'docsify-demo',
            // 倉庫地址，點選右上角的Github章魚貓頭像會跳轉到此地址
            repo: 'https://github.com/zjcscut/docsify-demo',
            // 側邊欄支援，預設載入的是專案根目錄下的_sidebar.md檔案
            loadSidebar: true,
            // 導航欄支援，預設載入的是專案根目錄下的_navbar.md檔案
            loadNavbar: true,
            // 封面支援，預設載入的是專案根目錄下的_coverpage.md檔案
            coverpage: true,
            // 最大支援渲染的標題層級
            maxLevel: 4,
            // 自定義側邊欄後預設不會再生成目錄，設定生成目錄的最大層級，建議配置為1或者2
            subMaxLevel: 2
        }
    </script>
    <script>
        // 搜尋配置
        window.$docsify = {
            search: {
                maxAge: 86400000,
                paths: auto,
                placeholder: '搜尋',
                noData: '找不到結果',
                depth: 4,
                hideOtherSidebarContent: false,
                namespace: 'docsify-demo',
            }
        }
    </script>
    <!-- docsify的js依賴 -->
    <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
    <!-- emoji表情支援 -->
    <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/emoji.min.js"></script>
    <!-- 圖片放大縮小支援 -->
    <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/zoom-image.min.js"></script>
    <!-- 搜尋功能支援 -->
    <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
</body>

</html>

還有更多配置項可以參考docsify文件中的定製化 - 配置項一小節，定製的東西越多，維護的難度就越大。側邊欄、導航欄和封面都建議採用預設的檔案渲染：

元件	檔案
側邊欄	`/_sidebar.md`
導航欄	`/_navbar.md`
側邊欄	`/_coverpage.md`

側邊欄與導航欄

導航欄需要在根目錄的index.html或者_navbar.md檔案中配置，可以使用emoji，這裡修改index.html檔案如：

<!-- index.html -->

<body>
  <nav>
    <a href="https://throwx.cn">?? Throwable's Blog</a>
    <a href="https://spring.throwx.cn">❤️❤️ Spring專欄</a>
  </nav>
  <div id="app">載入中......</div>
</body>

效果如下：

側邊欄需要在根目錄的_sidebar.md檔案中配置，基本的格式是：

* 第一個章節的標題

 * [第一個章節第1篇文章的標題](第一個章節第1篇文章的標題的markdown檔案)
 * [第一個章節第2篇文章的標題](第一個章節第2篇文章的標題的markdown檔案)
 ......

* 第二個章節的標題

 * [第二個章節第1篇文章的標題](第二個章節第1篇文章的標題的markdown檔案)
 * [第二個章節第2篇文章的標題](第二個章節第2篇文章的標題的markdown檔案)
 ......

渲染後的側邊欄效果是：

第一個章節的標題
   - 第一個章節第1篇文章的標題
   - 第一個章節第2篇文章的標題
第二個章節的標題
   - 第二個章節第1篇文章的標題
   - 第二個章節第2篇文章的標題

主題切換

切換主題只需要在根目錄的index.html切換對應的主題css檔案即可

目前docsify官方中列出來的所有支援主題和預覽效果如下：

Vue（預設主題）：<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">

Buble：<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/buble.css">

Dark：<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/dark.css">

Pure：<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/pure.css">

Dolphin：<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/dolphin.css">

Docsify-Themeable-Default：<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-defaults.css">

Docsify-Themeable-Sample：<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple.css">

Docsify-Themeable-Sample-Dark：<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple-dark.css">

最有一款合你心水。

設計封面

封面需要在根目錄的_coverpage.md檔案中配置，例如docsify官方文件的封面內容如下：

<!-- _coverpage.md -->

![logo](https://throwable-blog-1256189093.cos.ap-guangzhou.myqcloud.com/202009/_media/icon.svg)

# docsify <small>3.5</small>

> 一個神奇的文件網站生成器。

- 簡單、輕便 (壓縮後 ~21kB)
- 無需生成 html 檔案
- 眾多主題

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

渲染效果如下：

筆者也參照此配置做了一個醜醜的主頁，內容如下：

![logo](https://throwable-blog-1256189093.cos.ap-guangzhou.myqcloud.com/202009//leaf.svg)

# Spring Album <small>0.0.1</small>

> 試下寫個Spring相關的專欄，這是原始版本，暫定包括下面的欄目：

- `SpringBoot2.x`入門系列 
- `SpringBoot2.x`進階和實戰
- `SpringBoot`原始碼系列

[GitHub](https://github.com/zjcscut/spring-boot-guide)
[Get Started](#Spring)

渲染效果如下：