小技巧：用 GitBook 組織 Markdown 文檔

喜歡用 Markdown 寫文檔，那怎麼把一個個 Markdown 文檔組成在一塊兒呢？

這篇文章，分享了一個用 GitBook 來組織 Markdown 文檔的辦法。一塊兒瞭解下吧。

Markdown 是一種輕量級標記語言。只需人們純文本編寫文檔，加上點標記符號，就能轉成有格式的文檔（如 HTML 富文本）。已普遍應用在筆記、文檔、博客、出書等。2016 年 RFC 7763 開始也引入了 MIME 類型 text/markdown 。

1 準備工具

1. 安裝 Node.js: https://nodejs.org/
2. 安裝 GitBook: https://www.npmjs.com/package...

npm install gitbook-cli -g

最終，終端裏可執行 gitbook :

$ gitbook -V
CLI version: 2.3.2
GitBook version: 3.2.3

2 準備文檔

2.1 建立文檔目錄

mkdir start-gitbook

2.2 建立說明文件 README.md

README.md 是 GitBook 的必要文件

echo "# My GitBook" > README.md

2.3 建立目錄文件 SUMMARY.md

SUMMARY.md 是 GitBook 的必要文件

cat <<EOF > SUMMARY.md
# Summary

This is the summary of my book.

* [section 1](section1/README.md)
  * [example 1](section1/example1.md)
  * [example 2](section1/example2.md)
* [section 2](section2/README.md)
  * [example 1](section2/example1.md)
EOF

編輯組織已經存在的 Markdown 文檔路徑。新建的項目，則寫預想的文檔結構。

2.4 建立文檔結構

依照 SUMMARY.md ，建立新項目的文檔結構。

$ gitbook init
info: create section1/README.md
info: create section1/example1.md
info: create section1/example2.md
info: create section2/README.md
info: create section2/example1.md
info: create SUMMARY.md

2.5 預覽文檔

$ gitbook serve
Live reload server started on port: 35729
Press CTRL+C to quit ...

info: 7 plugins are installed
info: loading plugin "livereload"... OK
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 6 pages
info: found 0 asset files
info: >> generation finished with success in 0.5s !

Starting server ...
Serving book on http://localhost:4000

瀏覽器打開 http://localhost:4000 ，便可預覽。效果以下：

3 生成文檔

默認生成 HTML 文檔，在 _book 目錄。若是要生成其餘格式，須要安裝 ebook-convert 插件。

3.1 安裝 ebook-convert 插件

安裝 Calibre: https://calibre-ebook.com/dow... ，並配置好終端 ebook-convert 命令。

Ubuntu 直接安裝：

sudo aptitude install calibre

macOS 下載安裝，並配置軟連接：

ln -s /Users/John/Applications/calibre.app/Contents/MacOS/ebook-convert /usr/local/bin

最終，終端裏可執行 ebook-convert :

$ ebook-convert --version
ebook-convert (calibre 4.17.0)
Created by: Kovid Goyal <kovid@kovidgoyal.net>

3.2 生成 PDF 文檔

$ gitbook pdf ./ ./mybook.pdf
info: 7 plugins are installed
info: 6 explicitly listed
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 6 pages
info: found 1 asset files
info: >> generation finished with success in 5.7s !
info: >> 1 file(s) generated

3.3 生成 ePub 文檔

$ gitbook epub ./ ./mybook.epub
info: 7 plugins are installed
info: 6 explicitly listed
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 6 pages
info: found 1 asset files
info: >> generation finished with success in 1.9s !
info: >> 1 file(s) generated

3.4 生成 MOBI 文檔

$ gitbook mobi ./ ./mybook.mobi
info: 7 plugins are installed
info: 6 explicitly listed
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 6 pages
info: found 1 asset files
info: >> generation finished with success in 1.6s !
info: >> 1 file(s) generated

3.5 PDF 預覽效果

結語

Go coding!

---

分享 Coding 中實用的小技巧、小知識！歡迎關注，共同成長！