用Markdown寫電子書－使用mdBook超簡單

✍📝 v1.0 2020/04/23 Jerry
✍📝 v1.1 2020/04/26 Jerry

1. mdBook是什麼？

mdBook簡介

mdBook是使用Rust語言開發的工具，用來將Markdown格式的文件轉換成書本格式，適合技術文件、電腦使用說明文件等埸合。mdBook也是開源軟體，以命令行的方式執行。

mdBook產生的HTML書籍格式仿照GitBook，左側是章節目錄（Table of Contents），右側是內容，可變換主題樣式，且有全文檢索功能（可惜搜尋不到中文字），同時也提供列印刷，但目前尚無法匯出PDF。

mdBook相關資源

• 官網：rust-lang/mdBook: Create book from markdown files. Like Gitbook but implemented in Rust
• 下載：Releases · rust-lang/mdBook
• 使用說明：mdBook - mdBook Documentation
• 簡體中文使用說明（非官方）

2. mdBook的安裝與初次執行

說明安裝與執行的步驟。

2.1. 下載

首先由網頁 Releases · rust-lang/mdBook 下載使用平台的壓縮檔後，解壓縮後即可使用。Windows平台解開的是mdbook.exe，將此執行檔複製到PATH指到的路徑內即可。

2.2. 初次執行

在要存放書本的資料夾內執行指令mdbook init並回應內容：

2.2.1. 啟始環境

mdbook init

Do you want a .gitignore to be created? (y/n)
y
What title would you like to give the book?
我的第一本網頁書
2020-04-23 18:04:31 [INFO] (mdbook::book::init): Creating a new book with stub content

All done, no errors...

💡 要產生樣式檔則使用mdbook init --theme，/src會多出theme子目錄

mdBook自動產生書本的原始架構與相關檔案。目錄結構如下：

存放書本的資料夾/
├── book
└── src
    ├── chapter_1.md
    └── SUMMARY.md

2.2.2. 組建書本

子目錄與檔案都產生後以下列指令執行第一次組建：

mdbook build

一切正常的話表示 book 資料夾內已有需要的網頁檔案了，再來啟動測試用的網頁伺服器：

mdbook serve

2.2.3. 檢視輸出

最後用瀏覽器瀏覽 http://localhost:3000，一切無誤的話會看到預設的網頁內容。

2.2.4. 頁面基本操作

圖示	操作	說明
	目錄與內容	左右變更大小
	切換目錄	顯示或隱藏最左側的章節目錄
	跳至下一章節	顯示下一章節網頁
	跳至上一章節	顯示上一章節網頁
	全文檢索	搜尋輸入的文字
	變更主題	變更顯示的頁面樣式
	切換目錄	顯示或隱藏最左側的章節目錄

3. 書本設定：book.toml

開始說明mdBook電子書的組織方法。

電子書的基本設定資料是存放在根目錄的book.toml檔案。

▼ 範例：

[book]
authors = ["jdev.tw]
language = "zh"
multilingual = false
src = "src"
title = "用Markdown寫電子書：使用mdBook超簡單"

4. 控制主文件：SUMMARY.md

SUMMARY.md是整本書的主要控制文件，左側的章節超連結即由SUMMARY.md組成。它由三大部份組成，每個部份可有多個項目：

4.1. 開頭部份

[開頭](開頭.md)

4.2. 章節部份

* [第一章](第一章.md)
    * [第一節](第一章第一節.md)
    * [第二節](第一章第二節.md)
    * ...
* [第二章](第二章.md)
    * [第一節](第二章第一節.md)
    * [第二節](第二章第二節.md)    
    * ...
* ...

4.3. 結尾部份

[結尾](結尾.md)

範例

# 用Markdown寫書：使用mdBook超簡單

[修改歷程](./README.md)

----

- [mdBook是什麼？](./chapter_1.md)
- [mdBook的安裝與初次執行](./chapter_2.md)
    - [下載](./chapter_2.1.md)
    - [初次執行](./chapter_2.2.md)
- [書本設定：book.toml](./chapter_3.md)
- [控制主文件：SUMMARY.md](./chapter_4.md)
- [打包與部署](./chapter_5.md)

----

[宣告事項](./footer.md)

5. 注意事項

第一次使用mdBook時遇到了下列狀況：

1. 檔案儲存格式應使用UTF-8不帶BOM，UTF-8帶BOM的格式會無法解析Markdown語法
2. 圖片標記中的提示文字不可為空，為空時會組建失敗

▼ 下列語法會出現錯誤：

![](https://bit.ly/3eJwnOZ)

▼ 加上文字即可正常：

![text](https://bit.ly/3eJwnOZ)

宣告事項

💓❤🧡💛💚💙💜💖 感謝您的觀看。

🙏 敬請分享與訂閱

🙋‍♂️ 萬分感謝！👍👍👍