學習撰寫文件，初識好幫手 docsify

一起認識 docsify，整理好專案文件

Lai

Published in

UnaLai

8 min readJun 21, 2020

以往筆者都是使用 HackMD、Notion、Google Sheet 等工具紀錄專案資訊，後來發現資訊會變得有些散落，雖然大致上都能夠知道自己把資料放在哪邊，但可能再過更久一些，就會失憶了，有一天需要交接專案可能會面臨資訊不完整的困境。

目前沒有太多文件撰寫經驗，因此決定直接嘗試強強夥伴 Chris 🤩推薦的 docsify，此篇紀錄 docsify 入門筆記。

Outline
* 介紹 docsify
* 開始撰寫 docsify
  * 安裝、初始化、預覽
  * 介紹初始資料夾
  * 建立主要頁面
  * 製作側邊導航欄
  * 增加子項目頁面
  * 製作導航欄
  * 添加 emoji
  * 增加搜尋功能
* 參考資料

➤ 介紹 docsify

docsify 是一個用以撰寫文件的工具。其特色為輕巧、沒有靜態生成的多個 html 文件、多個套件支援等。

➤ 開始撰寫 docsify ✏

安裝、初始化、預覽

全局安裝

npm i docsify-cli -g

初始化，產生初始資料夾

docsify init ./docs

本地預覽

docsify serve docs

初始化後的預覽結果：

介紹初始資料夾

認識以下幾個基本文件：

index.html：docsify 進入點
README.md ：作為首頁渲染
.nojekyll：若部署於 GitHub Pages，需建立此文件。阻止 GitHub Pages忽略下劃線開頭的文件(docsify 設定過程會有許多下劃線開頭的文件)。

建立主要頁面

目前筆者的專案文件需要以下大項目(可根據個人需求調整)：

需求規格 (spec)
時程安排 (schedule)
開發者技術 (dev)
API 文件 (api)
DB schema (dbSchema)
其他文件紀錄 (otherDocument)

每一個大項目，建立一個資料夾管理，並於資料夾中建立一份 README.md 作為項目首頁。目前建立結果如下：

以 API 文件為例，在網址列中輸入 http://localhost:3000/#/api/ ，即可看見api 資料夾中 README.md 檔案內容，例如：

製作側邊導航欄

於 index.html 檔案中，設定 docsify 使用 loadSidebar 選項

<script>
window.$docsify = {
  name: '專案文件',
  loadSidebar: ture
}
</script>

接著於 docs 底下建立 _sidebar.md 檔案，用以設定側邊導航欄內容。如下設定：

* [需求規格](/spec/ "需求規格")
* [時程安排](/schedule/ "時程安排")
* [開發者技術](/dev/ "開發者技術")
* [API 文件](/api/ "API 文件")
* [DB schema](/dbSchema/ "DB schema")
* [其他文件紀錄](/otherDocument/ "其他文件紀錄")

其中 [ ] 內代表側邊欄顯示文字，( ) 內代表路徑，路徑後代表該頁面的網頁 title 。

結果顯示如下：

增加子項目頁面

例如在規格底下，想要新增會員及訂單兩個子項目。

首先一樣新增相對應的資料夾、檔案

設定側邊導航欄

* [需求規格](/spec/ "需求規格")
  * [訂單](/spec/order/ "訂單規格")
  * [會員](/spec/user/ "會員規格")
* [時程安排](/schedule/ "時程安排")
* [開發者技術](/dev/ "開發者技術")
* [API 文件](/api/ "API 文件")
* [DB schema](/dbSchema/ "DB schema")
* [其他文件紀錄](/otherDocument/ "其他文件紀錄")

子項目的部分，利用縮排來分辨。結果如下：

製作導航欄

於 index.html 檔案中，設定 docsify 使用 loadNavbar 選項

<script>
window.$docsify = {
  name: '專案文件',
  loadSidebar: ture,
  loadNavbar: ture
}
</script>

接著於 docs 底下建立 _navbar.md 檔案，用以設定側邊導航欄內容。如下設定：

* [需求規格](/spec/)
* [時程安排](/schedule/)
* [開發者技術](/dev/)
* [API 文件](/api/)
* [DB schema](/dbSchema/)
* [其他文件紀錄](/otherDocument/)

結果如下：

也可以嘗試另外一種下拉清單的方式，_navbar.md 需要這樣設定：

* 專案文件
  * [需求規格](/spec/)
  * [時程安排](/schedule/)
  * [開發者技術](/dev/)
  * [API 文件](/api/)
  * [DB schema](/dbSchema/)
  * [其他文件紀錄](/otherDocument/)

效果如下：

添加 emoji

於 index.html 檔案中，引入 emoji 插件

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

在專案中使用，例如導航欄

* :blue_book: 專案文件
  * [需求規格](/spec/)
  * [時程安排](/schedule/)
  * [開發者技術](/dev/)
  * [API 文件](/api/)
  * [DB schema](/dbSchema/)
  * [其他文件紀錄](/otherDocument/)

效果如下：

emoji 可以參考這邊：點我查看

增加搜尋功能

於 index.html 檔案中，設定 docsify 使用 search 功能

<script>
window.$docsify = {
  name: '專案文件',
  loadSidebar: true,
  loadNavbar: true,
  search: {
    maxAge: 86400000,
    paths: 'auto',
    placeholder: '搜尋',
    noData: '找不到結果',
    depth: 6
  }
}
</script><!-- 引入套件 -->
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>

搜尋功能套件會建立內容索引於 localStorage 內，默認時間是一天，可調整 maxAge 更改時間。

效果如下：