使用開源文檔工具docsify，用寫博客的姿勢寫文檔

本文轉載自查看原文 2020-09-03 00:27 4533

前提

下面的簡介摘抄自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)

渲染效果如下：