docsify , 網站文件動態生成工具，類似gitbook

特性

• 無需構建，寫完文件直接釋出
• 容易使用並且輕量 (~19kB gzipped)
• 智慧的全文搜尋
• 提供多套主題
• 豐富的 API
• 支援 Emoji
• 相容 IE10+
• 支援 SSR

安裝

npm i docsify-cli -g

進入專案根目錄並初始化

docsify init ./docs

之後docs目錄下會生成以下幾個檔案

index.html 入口檔案
README.md 會做為主頁內容渲染
.nojekyll 用於阻止 GitHub Pages 會忽略掉下劃線開頭的檔案
 

執行服務

docsify serve ./docs

開啟瀏覽器 http://localhost:3000

多頁文件

建立多個頁面，或者多級路由。建立一個 guide.md 檔案，那麼對應的路由就是 /#/guide。

例如這樣一個目錄結構

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

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

設定封面

設定 coverpage 引數

window.$docsify = {
    coverpage: true
  }

接著在根目錄建立 _coverpage.md 檔案

背景自定義

預設的背景是隨機生成的漸變色

如要自定義背景圖片或者背景色，在_coverpage.md中設定如下內容

<!-- 背景圖片 -->

![](_media/bg.png)

<!-- 背景色 -->

![color](#f0f0f0)

自定義導航欄

直接在 HTML 裡定義導航欄，連結以 #/ 開頭

在index.html的body中新增以下程式碼

<nav>
    <a href="#/">EN</a>
    <a href="#/zh-cn/">中文</a>
  </nav>
  <div id="app"></div>
 

接著配置 loadNavbar

window.$docsify = {
    loadNavbar: true
  }

在navbar.md_中新增以下連結

* [En](/)
* [中文](/zh-cn/)

側邊欄導航

預設側邊欄會根據當前文件的標題生成目錄。也可以設定文件連結，通過 Markdown 檔案生成

先配置 loadSidebar 選項

window.$docsify = {
    loadSidebar: true
  }

然後建立 _sidebar.md 檔案，這樣我們左側目錄就會顯示出來

* [首頁](zh-cn/)
* [指南](zh-cn/guide)

需要在文件根目錄建立 .nojekyll 命名的空檔案，阻止 GitHub Pages 忽略命名是下劃線開頭的檔案。

外掛

新增全文搜尋
引入search.js

<script src="//unpkg.com/docsify/lib/plugins/search.js"></script>

配置search選項

search: {
      maxAge: 86400000, // 過期時間，單位毫秒，預設一天
      paths: [], // or 'auto'
      placeholder: 'Type to search',

      // 支援本地化
      placeholder: {
        '/zh-cn/': '搜尋',
        '/': 'Type to search'
      },

      noData: 'No Results!',

      // 支援本地化
      noData: {
        '/zh-cn/': '找不到結果',
        '/': 'No Results'
      },
      // 搜尋標題的最大程級, 1 - 6
      depth: 2
    }

新增評論系統

Gitalk，一個現代化的，基於Preact和Github Issue的評論系統。

<link rel="stylesheet" href="//unpkg.com/gitalk/dist/gitalk.css">

<script src="//unpkg.com/docsify/lib/plugins/gitalk.min.js"></script>
<script src="//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>

clientID和clientSecret需要在github上建立一個app生成

相關連結

• docsify
• shields