最簡單的Markdown文檔生成工具 book-cli

目前的文檔編寫工具，我想大概推薦：

• gitbook
• vuepress
• ydoc

其他的我都不太清楚了，還有一些國内文檔編寫的網站，各種選擇。

是的，造輪子的人又來了。

當下的問題：

gitbook

我就不說了，代碼老舊，控件庫品質層次不齊，我改了一天，勉強能看，再弄弄，居然有bug，果斷放棄。

還有上傳同步那一套，搞得我摸不清頭腦....

vuepress

尤大的團隊，還是很值得信任的，功能我看了，是夢想中的功能。

當時寫一半的時候看到vuepress，當時有考慮過直接用vuepress。

隻是吧，文檔居然能有那麼長，然後又是安裝，又是部署，想想應該沒有多少人通路的網站，我還是自己寫個吧。

ydoc

我覺得ydoc還是很不錯的，就是我在一開始寫文檔的時候，一直想不起名字，導緻，我一直沒有找到它。

但是，我剛剛試用了一下，還是很多細節有欠缺，感覺自己改起來應該比較麻煩。

比如說，傳回頂部，或者段落标題hash，和vuepress相比的話，缺乏很多細節。

不多說了，總之，自己寫的用起來比較爽，好改。

Book-Cli

book-cli 是一個簡單的靜态頁面，用于快速生成說明文檔網站。

簡單來說，book-cli 不需要編譯，你可以通過直接編寫

Markdown

檔案，達到文檔網站的建構。

它是如何工作的？

其實，book-cli 是通過

marked

,

prism

等控件，直接使用

javascript

讀取

Markdown

檔案，解析檔案，再渲染頁面。

是以，不需要編譯，自動化部署簡單（送出代碼即可），入門難度極低。

初始化項目

我們提供以下三種方案初始化項目：

下載下傳代碼

建議從 book-cli 的 github 中下載下傳代碼至本地。

Fork

在github中直接fork項目。

項目拷貝

使用git拷貝項目，以下為示例代碼：

git clone https://github.com/vvpvvp/book-cli.git my-project
  git remote set-url origin my-project-github-address
  git push
複制代碼
           

當然，你也可以通過其他方式初始化項目，簡單的來說，就是代碼拷貝。

配置

根目錄下

config.js

檔案

var CONFIG = {
  // 網頁 title
  title: 'Book-Cli',
  // 網頁 keywords
  keywords: 'book, book-cli, doc, example',
  // 網頁 description
  description: 'Init html book with markdown files.',
  // 頁面右上角的 github 連結
  github: 'https://github.com/vvpvvp/book-cli',
  // 左側目錄的md檔案
  summaryMd: 'SUMMARY.md',
  // 網頁預設通路的md檔案
  index: 'README.md'
}
複制代碼
           

部署

編寫完文檔後，将整個目錄上傳至服務上，設定通路即可。

Github 部署

Github提供了免費的靜态頁面部署服務，是以，你可以免費的釋出自己的文檔項目。

項目 -> Setting -> GitHub Pages -> 選擇master分支 -> 點選Save

之後，你就可以通路文檔網站了。

維護

項目維護極其簡單，直接維護md文檔就可以了。

優缺點

優點

• 快速入門
• 無需編譯
• 快速部署（靜态系統，随意扔在伺服器上即可）
• 自定義極強（純靜态系統，可以随意修改）
• 适配PC端與移動端
• 界面好看（臉皮較厚）

缺點

• 未編譯成html，對于搜尋引擎不友好（其實作在搜尋引擎隻需要收錄下首頁）
• 功能沒有那麼強大
• 沒有全網搜尋

最後

說了那麼多，期待大家的嘗試-->期待star ✨✨

github.com/vvpvvp/book…

線上文檔：

vvpvvp.coding.me/book-cli/#R…

示例文檔（我自己整理的ECMAScript 6文檔）:

es6.ch-un.com/

最後的最後

希望大家關注我的Vue開源庫 HeyUI