[推薦] 使用markdown撰寫文件網站的好工具-Docsify

      在〈[推薦] 使用markdown撰寫文件網站的好工具-Docsify〉中尚無留言

開發有時候會有需要寫文件的需求，以前比較熱門會使用 gitbook 來寫，gitbook 好處是撰寫 markdown 並且可以編譯成 html 靜態網頁來使用以及依據需求安裝套件，不過可惜的是後來 gitbook-cli 不再更新，使得套件也漸漸的減少更新了。而現在有類似的替代方案 vuepress 與 docsify，其也是使用 markdown 的方式撰寫文件並且可以安裝套件，且優點是不需要編譯以及快速使用，本篇將教學如何安裝與使用 docsify。

官方網站：https://docsify.js.org

原始碼：https://github.com/docsifyjs/docsify/

使用 npm 安裝 docsify-cli (需先安裝 node.js)

npm i docsify-cli -g

接著就能使用 docsify-cli 建立文件專案 (my-docs 是資料夾名稱)

docsify init ./my-docs

建立完的專案一開始會有3個檔案

  • index.html 網站的進入點，用來設定以及安裝套件
  • README.md 首頁內容
  • .nojekyll 其用途是避免 github pages 會自動忽略調一些底線開頭的檔案，如果輸出並不是架在 github 上，並不是那麼的重要

而要使用 hot reload 可使用 serve 的指令來開啟（如果不需要使用 hot reload 功能，可直接把資料夾放到任何host用瀏覽器開啟就好）

docsify serve my-docs

serve 開啟用就用瀏覽器開啟顯示的網址就能開始撰寫了

基本設定

在 index.html 裡面有段 javascript code 用來做一些 docsify 的設定

<script>
  window.$docsify = {
    name: 'Xenby Demo',
    repo: 'https://xenby.com'
  }
</script>

其中 name 是用來設定左上方的標題，而 repo 則是設定視窗右上方的 github 連結

更換主題

docsify 可以隨意更換自己喜歡的主題

※ 可以在頁面查看有什麼主題可以使用： https://jhildenbiddle.github.io/docsify-themeable/#/

只需要在 index.html 中載入對應的主題 css 便可

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

路徑對應網址

接著說明檔案路徑與對應檔案的關係

.
├── guidelines
│   ├── coding-style.md
│   └── unittest.md
├── index.html
├── introduction.md
└── README.md

假設新增了3個檔案 guidelines/coding-style.md、guidelines/unittest.md 以及 introduction.md (檔案內需要有內容否則會顯示 404)

而這3個網站對應的路徑就會是

檔案 網址
guidelines/coding-style.md http://host/#/guidelines/coding-style
guidelines/unittest.md http://host/#/guidelines/unittest
introduction.md http://host/#/introduction

設定側邊欄

了解網址對應後，接著就能開始來設定側編欄

首先要在 index.html 中啟用讀取側編欄 loadSidebar

<script>
  window.$docsify = {
    ...
    loadSidebar: true,
  }
</script>

接著就是在資料夾中建立 _sidebar.md 側編欄檔案，內容就可以用來設定側編欄

* [首頁](/)
* [介紹](/introduction)
  * [Coding Style](/guidelines/coding-style)
  * [單元測試](/guidelines/unittest)

啟用套件

docsify 安裝套件非常簡單，只需要在 index.html 中將對應的 javascript 讀取進去並加上設定就可以了

※ 可以在頁面查看有什麼套件可以使用：

這邊以 Search 套件為範例，首先我們加上在 index.html 中加上套件網址 (放在 docsify.min.js 之後)

<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>

接著再將對應的設定加上

window.$docsify = {
    ...
    search: 'auto',
}

發表迴響