Markdown 文檔生成工具

之前用了很多Markdown 文檔生成工具，發現有幾個挺好用的，現在整理出來，方便大家快速學習。

• loppo: 非常簡單的靜態站點生成器
• idoc：簡單的文檔生成工具
• gitbook：大名鼎鼎的文檔協作工具
• docsify：一個神奇的文檔站點生成器，簡單輕巧，無需靜態構建html

教程版：
http://me.52fhy.com/learn-markdown-generate-tool/#/

loppo

官網： https://github.com/ruanyf/loppo

依賴 node.js 環境。

特點：
1、簡單小巧，支持自動生成目錄。
2、不支持插件。
3、原理是將 Markdown 文件編譯生成 html 文件。
4、生成的頁面很美觀、大方，支持響應式。

安裝

全局安裝：

$ npm install loppo -g

如何使用

創建項目：

$ mkdir test-loppo
$ cd test-loppo

項目目錄格式示例：

|- test-loppo
   |- README.md
   |- docs
      |- page1.md
      |- page2.md
      |- ...

然后運行項目：

$ loppo 

會生成：

dist/
chapters.yml
loppo.yml

其中 dist是編譯輸出目錄；chapters.yml是自動生成的文檔目錄，根據當前目錄生成，如果增刪了源文件，需要刪除該文件使得下次重新生成；loppo.yml是配置文件，第一次生成后不會再變更。

loppo.yml

該文件是配置文件：

dir: docs
output: dist
site: Documents
theme: oceandeep
customization: false
themeDir: loppo-theme
direction: ltr
id: test-loppo

我們可以手動進行修改。

• dir： 源文件所在目錄。默認是當前目錄下的 docs目錄。
• output：編譯輸出文件目錄。
• site：項目文檔名稱。可以自定義，顯示在頁面 title 里。
• theme：主題。默認oceandeep。暫時不知道有沒有其他主題。

示例項目

• ruanyf/survivor: 博客文集《未來世界的幸存者》
  https://github.com/ruanyf/survivor

預覽地址：http://survivor.ruanyifeng.com/

• ruanyf/road: 博客文集《前方的路》
  https://github.com/ruanyf/road

預覽地址：http://road.ruanyifeng.com/

• 飛鴻影~的博客文集
  http://wen.52fhy.com/

• 安卓學習筆記
  http://android.52fhy.com/

idoc

官網： https://github.com/jaywcjlove/idoc

依賴 node.js 環境。

特點：
1、簡單小巧，支持自動生成目錄。有幾個主題可以選擇。
2、不支持插件。
3、原理是將 Markdown 文件編譯生成 html 文件。

安裝

全局安裝：

$ sudo npm install idoc -g

如何使用

創建並初始化項目：

$ mkdir test-idoc
$ cd test-idoc

# 初始化
$ idoc init 

填入必要的項目信息，初始化完成。會在項目目錄下生成：

md/
 |-- index.md
package.json

運行 idoc server 預覽生成的靜態頁面。默認預覽地址為 http://localhost:1987/

預覽的時候改動md文件，瀏覽器刷新可以看到改動后的內容。

其中 初始化 步驟也可以手動執行，把目錄和配置文件建好就行了。

目錄結構

idoc對目錄結構沒有要求，只要你把md文件放在md/目錄下面，idoc會自動識別。支持子目錄。例如：

md/
 |-- 首頁.md
 |-- 關於.md
 |-- 使用方法/
	|-- 命令文檔.md
	|-- 命令文檔2.md

如果有子目錄，生成的文檔導航欄也會有子菜單。效果：

配置文件

package.json文件。

{
    "name": "idoc",
    "version": "0.0.1",
    "description": "",
    "keywords": [
        ""
    ],
    "homepage": "http://JSLite.io",
    "author": "jaywcjlove <[e-mail]>",
    "repository": {
        "type": "git",
        "url": "https://github.com/jaywcjlove/idoc"
    },
    "licenses": "MIT",
    "idoc": {
        "theme": "default",
        "logo": "idoc-logo.svg",
        "md": [
            "首頁.md",
            {
                "使用方法": [
                    "主題文件.md",
                    "初始化.md",
                    "配置說明.md"
                ]
            },
            "關於.md"
        ]
    }
}

其中 idoc.md塊無需手動配置，idoc build 自動生成。其它配置無需多說明，也能看的懂。

主題

支持：

• handbook
• default
• resume

參考：https://wangchujiang.com/idoc/html/主題.html

常用命令

• build

生成靜態 HTML 頁面到指定目錄中。

$ idoc build

• watch

監控 md 文件發生變化自動 build。

$ idoc watch

• server

打開本地靜態 html 服務器，預覽你生成的頁面。

$ idoc server

• clean

清除生成的靜態文件。

$ idoc clean

• theme

$ idoc theme 與 $ idoc -t 相同
選擇默認主題或者第三方主題，默認兩個主題 handbook 或者 default。

# 選擇主題
# 第三方主題，克隆到當前跟目錄就可以使用命令選擇了
$ idoc theme
# theme 簡寫 －t
$ idoc -t

# 制作主題 需要指定制作的主題目錄
$ idoc -t ~/git/idoc-theme-slate/

• deploy

將文檔部署到 git 倉庫的 gh-pages 分支中。
目前需要手動添加分支。

$ idoc deploy

示例項目

這些文檔是都是使用idoc生成的頁面：

1. JSLite.io - 這個是現代瀏覽器類似jQuery的庫，體積小。
2. idoc - 通過markdown生成靜態頁面的工具
3. store.js - js本地存儲操作
4. cookie.js - js本地cookie操作
5. iNotify - 瀏覽器各種方法通知
6. Nodejs教程
7. java代碼片段

gitbook

官網： https://www.gitbook.com/

依賴 node.js 環境。

特點：
1、擴展性非常好，有社區支持。支持插件。
2、目錄需要手動配置。
3、支持生成html、pdf、epub文件。

因為 gitbook 擴展性很強，下面僅給出簡要教程，詳細教程請閱讀：https://github.com/52fhy/gitbook-use

安裝

1、安裝 gitbook 編輯器：
https://legacy.gitbook.com/editor/

2、運行下面的命令進行安裝 gitbook-cli：

npm install gitbook-cli -g

其中 gitbook-cli 是 gitbook 的一個命令行工具, 通過它可以在電腦上安裝和管理 gitbook 的多個版本。

注意：

• gitbook-cli 和 gitbook 是兩個軟件
• gitbook-cli 會將下載的 gitbook 的不同版本放到 ~/.gitbook 中, 可以通過設置GITBOOK_DIR環境變量來指定另外的文件夾

如何使用

新建一個項目：

$ mdkir test_gitbook && cd test_gitbook

初始化目錄結構：

$ gitbook init

├── README.md
├── SUMMARY.md

使用下列命令會運行一個服務器, 通過http://localhost:4000/可以預覽書籍：

gitbook serve

運行該命令后會在書籍的文件夾中生成一個 _book 文件夾, 里面的內容即為生成的 html 文件。
我們可以使用下面命令來生成網頁而不開啟服務器。

gitbook build

目錄結構

GitBook 基本的目錄結構如下所示

├── book.json
├── README.md
├── SUMMARY.md
├── chapter-1/
|   ├── README.md
|   └── something.md
└── chapter-2/
    ├── README.md
    └── something.md

• book.json 為配置文件
• README.md 主頁
• SUMMARY.md 目錄文件

目錄文件

SUMMARY.md 示例：

# Summary
## 基本使用
* [前言](introduction.md)
* [安裝](installation.md)
* [命令](commands.md)
* [目錄結構](structure.md)
* [配置](settings.md)

## 擴展
* [插件](plugins.md)
* [主題](themes.md)
* [bookjson](bookjson.md)

配置文件

book.json 示例：

{
    "title": "Go Web編程",
    "description": "build-web-application-with-golang",
    "author": "謝孟軍",
    "output.name": "build-web-application-with-golang-zh",
	"pdf":{
		"fontFamily":"微軟雅黑"
	}
}

命令

列出gitbook所有的命令

gitbook help

輸出gitbook-cli的幫助信息

gitbook --help

下載所需的第三方插件依賴

gitbook install

生成靜態網頁並運行服務器

gitbook serve

生成靜態網頁

gitbook build

生成pdf

gitbook pdf

生成epub

gitbook epub

生成時指定gitbook的版本, 本地沒有會先下載

gitbook build --gitbook=2.0.1

列出本地所有的gitbook版本

gitbook ls

列出遠程可用的gitbook版本

gitbook ls-remote

安裝對應的gitbook版本

gitbook fetch 標簽/版本號

更新到gitbook的最新版本

gitbook update

卸載對應的gitbook版本

gitbook uninstall 2.0.1

指定log的級別

gitbook build --log=debug

輸出錯誤信息

gitbook builid --debug

注：生成pdf、epub需要安裝calibre插件，下載鏈接：https://calibre-ebook.com/download 。Mac 環境需要一個命令 sudo ln -s /Applications/calibre.app/Contents/MacOS/ebook-convert /usr/local/bin。

常見問題

1、gitbook生成pdf時缺少ebook.css
找到 C:\Users\YJC\.gitbook\versions\3.2.3\lib\output\website，將copyPluginAssets.js文件中67行和112行的“confirm: true” 改為：“confirm: false”。

示例項目

1、52fhy/gitbook-use: 記錄GitBook的一些配置及插件信息
https://github.com/52fhy/gitbook-use
2、Introduction · Go Web編程
http://doc.52fhy.com/build-web-application-with-golang/zh/index.html

docsify

官網： https://docsify.js.org/#/
代碼塊：https://github.com/docsifyjs/docsify

依賴 node.js 環境。

特點：
1、擴展性非常好，有社區支持。支持插件。
2、目錄需要手動配置。
3、發布無需編譯生成 html，動態解析 md 文件。

安裝

全局安裝：

npm i docsify-cli -g

如何使用

創建並初始化項目：

$ mkdir test-docsify
$ cd test-docsify

# init project
$ docsify init ./docs

執行完畢，生成 docs 目錄。里面有3個文件：

• .nojekyll：讓gitHub不忽略掉以 _ 打頭的文件
• index.html：整個網站的核心文件
• README.md：默認頁面

接下來預覽一下效果：

$ docsify serve docs

會在本地運行server服務，我們打開瀏覽器，輸入：http://localhost:3000 即可看到 demo 頁面。

項目的目錄結構示例：

.
└── 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

增加一個頁面

我們新增 guide.md 文件作為示例：

## docsify

官網： https://docsify.js.org/#/  
代碼塊：https://github.com/docsifyjs/docsify  

> 依賴 node.js 環境。

### 安裝

全局安裝：

npm i docsify-cli -g


### 如何使用

創建並初始化項目：

我們啟動 server 預覽效果：

$ docsify serve docs

瀏覽：http://localhost:3000/#/guide

效果截圖：

server 啟動后，我們修改文件保存后，瀏覽器會實時刷新。

Sidebar

我們可以給文檔增加左側菜單。菜單文件名是_sidebar.md。格式要求示例：

<!-- docs/_sidebar.md -->

* [Home](/)
* [Guide](guide.md)
* [About](about.md "關於我，這是title tag")

括號里可以增加 title tag，通常用於SEO。

保存后需要修改 index.html 添加loadSidebar: true以啟用左側菜單：

window.$docsify = {
  loadSidebar: true,
  subMaxLevel: 3,
  name: '',
  repo: '',
  auto2top: true,
  search: 'auto'
}

其中：

• loadSidebar：是否顯示左側菜單
• subMaxLevel：配置菜單層級，默認僅顯示一級
• name：配置項目名
• repo：配置代碼庫地址
• auto2top：更改路由時自動滾動到屏幕頂部
• search：配置啟用搜索功能。需要加載對應js文件。后面有說明。

效果：

也可以增加分組菜單，必須用tag鍵留空格，否則層級是相同的。示例：

* [首頁](/)
* 開始學習
	* [loppo](loppo.md "非常簡單的靜態站點生成器")
	* [idoc](idoc.md)
	* [gitbook](gitbook.md)
	* [docsify](docsify.md)
* 參考

配置高亮

docsify使用 Prism 突出顯示頁面中的代碼塊。默認情況下，它僅支持CSS，JavaScript和HTML。你可以使用 Prism 加載其他語言：

<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
<script src="//unpkg.com/prismjs/components/prism-bash.min.js"></script>
<script src="//unpkg.com/prismjs/components/prism-php.min.js"></script>
<script src="//unpkg.com/prismjs/components/prism-java.min.js"></script>
<script src="//unpkg.com/prismjs/components/prism-go.min.js"></script>
<script src="//unpkg.com/prismjs/components/prism-c.js"></script>
<script src="//unpkg.com/prismjs/components/prism-asm6502.js"></script>
<script src="//unpkg.com/prismjs/components/prism-makefile.js"></script>

從這個庫里獲取更多選項支持：https://github.com/PrismJS/prism/tree/gh-pages/components。

搜索

修改 index.html ，頭部引入：

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

然后配置里開啟搜索：

search: 'auto'

copy-code

如果需要支持代碼后面顯示復制按鈕，可以引入該插件：

<script src="//unpkg.com/docsify-copy-code"></script>

無需額外配置。

自定義導航欄

參考：https://docsify.js.org/#/custom-navbar

主題修改

僅需替換 index.html 里的vue：

<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css">

可用的主題：

<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css">
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/buble.css">
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/dark.css">
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/pure.css">

其它主題：
docsify-themeable ：A delightfully simple theme system for docsify.

參考：https://docsify.js.org/#/themes

配置參考

參考：https://docsify.js.org/#/configuration

插件參考

參考：https://docsify.js.org/#/plugins

發布到GitHub Pages

參考：https://docsify.js.org/#/deploy

示例項目

• 快速入門 - docsify
  https://docsify.js.org/#/quickstart

• 介紹 — Vue.js
  https://cn.vuejs.org/v2/guide/

• Linux C 編程一站式學習
  http://me.52fhy.com/linux-c/#/

參考資料

1、ruanyf/loppo: an extremely easy static site generator of markdown documents
https://github.com/ruanyf/loppo
2、docsify
https://docsify.js.org/
3、idoc
https://wangchujiang.com/idoc/index.html
4、52fhy/gitbook-use: 記錄GitBook的一些配置及插件信息
https://github.com/52fhy/gitbook-use
5、Mac環境安裝Gitbook，並導出PDF教程 - 簡書
https://www.jianshu.com/p/4824d216ad10