1. 什么是docsify

docsify 是一個動態(tài)生成文檔網(wǎng)站的工具久窟。不同于 GitBook、Hexo 的地方是它不會生成將 .md 轉成 .html 文件扳剿，所有轉換工作都是在運行時進行框杜。

這將非常實用贾节，如果只是需要快速的搭建一個小型的文檔網(wǎng)站，或者不想因為生成的一堆 .html 文件“污染” commit 記錄撮抓，只需要創(chuàng)建一個 index.html 就可以開始寫文檔而且直接部署在 GitHub Pages妇斤。

2. 使用docsify-cli來開發(fā)

2.2.1 安裝

docsify需要本地先安裝node, 如果沒有安裝node，可在node官網(wǎng)選擇對應操作系統(tǒng)下載安裝：https://nodejs.org/zh-cn/

終端輸入npm i docsify-cli -g進行全局安裝：

npm i docsify-cli -g

/usr/local/bin/docsify -> /usr/local/lib/node_modules/docsify-cli/bin/docsify
> fsevents@1.2.4 install /usr/local/lib/node_modules/docsify-cli/node_modules/fsevents
> node install
[fsevents] Success: "/usr/local/lib/node_modules/docsify-cli/node_modules/fsevents/lib/binding/Release/node-v57-darwin-x64/fse.node" already installed
Pass --update-binary to reinstall or --build-from-source to recompile
> docsify@4.8.6 postinstall /usr/local/lib/node_modules/docsify-cli/node_modules/docsify
> opencollective postinstall

                         Thanks for installing docsify ??
                 Please consider donating to our open collective
                        to help us maintain this package.

          ??  Donate: https://opencollective.com/docsify/donate

+ docsify-cli@4.3.0
added 456 packages from 206 contributors in 32.827s

image.png

安裝結束后使用docsify -v查看是否安裝成功：

docsify -v

docsify-cli version:
  4.3.0

2.2.2 初始化一個項目

首先需要創(chuàng)建一個項目目錄：

mkdir docsify

進入項目目錄后胀滚，使用docsify init ./來初始化一個項目：

cd docsify

docsify init ./docs

Initialization succeeded! Please run docsify serve docs

tree -a

.
├── .nojekyll
├── README.md
└── index.html

初始化成功后,docs目錄會生成如下幾個文件：

1. index.html入口文件
2. README.md會做為主頁內(nèi)容渲染
3. .nojekyll用于阻止 GitHub Pages 會忽略掉下劃線開頭的文件趟济、

.nojekyll文件很重要，如果網(wǎng)站部署到GitHub Pages時咽笼，一定要注意這個文件顷编。

直接編輯 ./README.md 就能更新網(wǎng)站內(nèi)容，當然也可以添加其他.md文件剑刑。

2.2.3 啟動本地服務

終端輸入docsify serve docs來啟動服務：

docsify serve docs

Serving /Users/dragon/tmp/docsify now.
Listening at http://localhost:3000

然后瀏覽器打開http://localhost:3000就能看見效果媳纬。

image.png

當修改文件保存后， docsify serve docs服務會自動實時更新施掏。

3. 關于每個頁面和URL路徑說明

如果需要創(chuàng)建多個頁面钮惠，或者需要多級路由的網(wǎng)站，在docsify里也能很容易的實現(xiàn)七芭。例如創(chuàng)建一個guide.md文件素挽，那么對應的路由就是/#/guide。
如果你的目錄結構如下：

-| ./
  -| README.md
  -| guide.md
  -| zh-cn/
    -| README.md
    -| guide.md

那么對應的訪問頁面將是:

./README.md        => http://domain.com
./guide.md         => http://domain.com/guide
./zh-cn/README.md  => http://domain.com/zh-cn/
./zh-cn/guide.md   => http://domain.com/zh-cn/guide

4. 側邊欄設置

默認情況下狸驳，側邊欄會根據(jù)當前文檔的標題生成目錄预明。

image.png

4.1 定制側邊欄

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

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

接著在項目根目錄創(chuàng)建_sidebar.md文件，內(nèi)容格式如下：

* [home1](home1)
* [home2](home2)
* [bar](bar/)
* [bar/a](bar/a)

image.png

注：配置了loadSidebar后就不會生成默認的側邊欄了耙箍。

4.2 關于側邊欄_sidebar.md文件的說明

• 如果只在根目錄有一個_sidebar.md文件撰糠，那么所有頁面都將使用這個一個配置，也就是所有頁面的側邊欄都一樣辩昆。
• 如果一個子目錄中有_sidebar.md文件阅酪，那么這個子目錄下的所有頁面將使用這個文件的側邊欄。
• _sidebar.md的加載邏輯是從每層目錄下獲取文件汁针，如果當前目錄不存在該文件則回退到上一級目錄术辐。例如當前路徑為/zh-cn/more-pages則從/zh-cn/_sidebar.md獲取文件，如果不存在則從/_sidebar.md獲取施无。

如果子目錄有_sidebar.md,但你就想使用根目錄的_sidebar.md术吗，
可在index.html文件中的window.$docsify添加alias字段：

<script>
  window.$docsify = {
    loadSidebar: true,
    alias: {
      '/.*/_sidebar.md': '/_sidebar.md'
    }
  }
</script>

配置alias字段后，所有頁面都會顯示項目根目錄_sidebar.md文件的配置作為側邊欄帆精，子目錄的_sidebar.md文件會失效较屿。

4.3 顯示頁面目錄(當前頁面的標題)

定制的側邊欄僅顯示了頁面的鏈接隧魄。
還可以設置在側邊欄顯示當前頁面的目錄(標題)。
需要在index.html文件中的window.$docsify添加subMaxLevel字段來設置：

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

image.png

subMaxLevel說明：

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

在md文件中標題的寫法：

# 這是一級標題映胁，對應HTML中<h1>標簽

## 這是二級標題，對應HTML中<h2>標簽

### 這是三級標題甲雅，對應HTML中<h3>標簽

#### 這是四級標題解孙，對應HTML中<h4>標簽

4.3.1 頁面的標題不在側邊欄目錄顯示

注意： 如果md文件的第一個標題是一級標題，那么默認已經(jīng)忽略了抛人。

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

# Getting Started

## Header {docsify-ignore}

該標題不會出現(xiàn)在側邊欄的目錄中廷臼。

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

# Getting Started {docsify-ignore-all}

## Header

該頁面所有標題都不會出現(xiàn)在側邊欄的目錄中绝页。

在使用時中剩， {docsify-ignore} 和 {docsify-ignore-all} 都不會在頁面上顯示。

5. 導航欄配置

docsify默認是沒有導航欄的抒寂，可以通過配置來顯示導航欄。

5.1 在index.html中定義導航欄

如果導航的鏈接少掠剑，則可以直接在index.html文件直接定義導航欄屈芜，要注意鏈接要以#/開頭：

<body>
  <nav>
    <a href="#/">項目</a>
    <a href="#/home1">home1</a>
    <a href="#/bar/a">bar/a</a>
  </nav>
</body>

image.png

5.2 通過配置文件定義導航欄

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

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

接著在項目根目錄創(chuàng)建_navbar.md文件，內(nèi)容格式如下：

* [home1](home1)
* [home2](home2)
* [bar](bar/)
* [bar/a](bar/a)

image.png

注意：
1.如果使用配置文件來設置導航欄朴译，那么在index.html中定義的導航欄只有在定制的首頁才會生效井佑，其他頁面會被覆蓋。
2.如果只在根目錄有一個_navbar.md文件眠寿，那么所有頁面都將使用這個一個配置躬翁，也就是所有頁面的導航欄都一樣。
3.如果一個子目錄中有_navbar.md文件盯拱，那么這個子目錄下的所有頁面將使用這個文件的導航欄盒发。
4._navbar.md的加載邏輯是從每層目錄下獲取文件例嘱，如果當前目錄不存在該文件則回退到上一級目錄。例如當前路徑為/zh-cn/more-pages則從/zh-cn/_navbar.md獲取文件宁舰，如果不存在則從/_navbar.md獲取拼卵。

5.3 導航欄嵌套

如果導航內(nèi)容過多，可以寫成嵌套的列表蛮艰，會被渲染成下拉列表的形式：

* 根目錄
  * [home1](home1)
  * [home2](home2)
  * [guide](guide)

* bar目錄
  * [bar](bar/)
  * [a文件](bar/a)
  * [b文件](bar/b)

* foo目錄
  * [one](foo/one)

image.png

6. 設置封面

docsify默認是沒有封面的腋腮，默認有個首頁./README.md。
通過設置coverpage參數(shù)壤蚜，可以開啟渲染封面的功能即寡。

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

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

接著在項目根目錄創(chuàng)建_coverpage.md文件，內(nèi)容格式如下：

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

* 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)

image.png

注：一份文檔只會在根目錄下加載封面袜刷，其他頁面或者二級目錄下都不會加載聪富。

6.1 自定義封面背景

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

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

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

image.png

注意：
1.自定義背景配置一定要在_coverpage.md文檔末尾。
2.背景圖片和背景色只能有一個生效.
3.背景色一定要是#2f4253這種格式的草则。

6.2 把封面作為首頁

配置了封面后钢拧，封面和首頁是同時出現(xiàn)的，封面在上面炕横，首頁在下面源内。
通過設置onlyCover參數(shù)，可以讓docsify網(wǎng)站首頁只顯示封面份殿，
原來的首頁通過http://localhost:3000/#/README訪問膜钓。

在index.html文件中的window.$docsify添加onlyCover: true,選項：

<script>
  window.$docsify = {
    coverpage: true,
    onlyCover: true,
  }
</script>
<script src="./docsify.min.js"></script>

通過此配置可以把./README.md文件獨立出來，當成項目真正的README介紹文件卿嘲。

6.3 多個封面

如果你的文檔網(wǎng)站是多語言的颂斜，或許你需要設置多個封面。
例如你的文檔目錄結構如下

.
└── docs
    ├── README.md
    ├── guide.md
    ├── _coverpage.md
    └── zh-cn
        ├── README.md
        └── guide.md
        └── _coverpage.md

那么你可以在index.html文件中的window.$docsify這么配置:

window.$docsify = {
  coverpage: ['/', '/zh-cn/']
};

或者具體指名文件名:

window.$docsify = {
  coverpage: {
    '/': 'cover.md',
    '/zh-cn/': 'cover.md'
  }
};

7. 網(wǎng)站部署到GitHub Pages

GitHub Pages 支持從三個地方讀取文件:

1拾枣、master分支
2沃疮、master分支下的docs目錄
3、gh-pages分支

1梅肤、如果你的文檔直接是在項目根目錄寫的司蔬，那么可直接把代碼推送到master分支上， GitHub Pages里選擇master branch.
2.如果你的文檔是在master分支下的docs/目錄下編寫的姨蝴，那么可直接把代碼推送到master分支上俊啼，GitHub Pages里選擇master branch/docs folder.

本例子項目是直接在根目錄中編寫的，所以GitHub Pages里選擇master branch的方式部署左医。

首先在github網(wǎng)站上創(chuàng)建好倉庫授帕，然后終端打開項目目錄：

git init
git add .
git commit -m 'docsify項目初始化'
git remote add origin https://github.com/username/docsify.git
git push --set-upstream origin master

代碼推送到github上后同木，打開github的倉庫，選擇Settings -> GitHub Pages -> master branch -> save豪墅。

image.png

image.png

7.1 使用docsify的例子

https://spiritree.github.io/n...

https://ripperhe.com/awesome-...

8. 一些插件

8.1 搜索插件

全文搜索插件會根據(jù)當前頁面上的超鏈接獲取文檔內(nèi)容泉手，在 localStorage 內(nèi)建立文檔索引。默認過期時間為一天偶器，當然我們可以自己指定需要緩存的文件列表或者配置過期時間斩萌。

<script>
    window.$docsify = {
      // 完整配置參數(shù)
      search: {
        maxAge: 86400000,               // 過期時間，單位毫秒屏轰，默認一天
        paths: [],                      // or 'auto'颊郎，匹配文件路徑
        placeholder: 'Type to search',  // 搜索提示框文字， 支持本地化霎苗，例子在下面
        // placeholder: {
        //   '/zh-cn/': '搜索',
        //   '/': 'Type to search'
        // },
        noData: 'No Results!',          // 找不到結果文字提示姆吭，支持本地化，例子在下面
        // noData: {
        //   '/zh-cn/': '找不到結果',
        //   '/': 'No Results'
        // },
        depth: 2,                       // 搜索標題的最大程級, 1 - 6
      }
    }
  </script>
  <!-- 引入搜索模塊 -->
  <script src="http://unpkg.com/docsify/lib/plugins/search.js"></script>

8.2 評論插件Gitalk

Gitalk：一個現(xiàn)代化的唁盏，基于Preact和Github Issue的評論系統(tǒng)内狸。
使用例子：

<link rel="stylesheet" >
<script src="http://unpkg.com/docsify/lib/plugins/gitalk.min.js"></script>
<script src="http://unpkg.com/gitalk/dist/gitalk.min.js"></script>
<script>
  const gitalk = new Gitalk({
    clientID: 'Github Application Client ID',
    clientSecret: 'Github Application Client Secret',
    repo: 'Github repo',
    owner: 'Github repo owner',
    admin: ['Github repo collaborators, only these guys can initialize github issues'],
    // facebook-like distraction free mode
    distractionFreeMode: false
  })
</script>

Gitalk具體使用教程：https://segmentfault.com/a/11...

docsify其他插件：https://docsify.js.org/#/zh-c...

8.3 樣式插件

在網(wǎng)上找到一個樣式：https://jhildenbiddle.github....

使用方法,在HTML文件中引入：

<link rel="stylesheet" >

參考資料

• docsify中文官網(wǎng)：https://docsify.js.org/#/zh-cn/

• https://segmentfault.com/a/1190000017576714