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

vvpvvp發表於2018-10-30

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

  • 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

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

之後，你就可以訪問文件網站了。

維護

專案維護極其簡單，直接維護md文件就可以了。

優缺點

優點

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

缺點

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

最後

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

github.com/vvpvvp/book…

線上文件：

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

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

es6.ch-un.com/

最後的最後

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

相關文章