用 Markdown 写电子书 / EPUB:自出版与排版入门
想自己出一本小书、教程合集或文档手册?用 Markdown 写正文、工具一键转 EPUB/MOBI,比在 Word 里折腾排版省心得多。本文讲清项目结构到导出的全流程。
用 Markdown 寫電子書 / EPUB:自出版與排版入門
想自己出一本小書、教學合集或文件手冊?用 Markdown 寫正文、工具一鍵轉 EPUB/MOBI,比在 Word 裡折騰排版省心得多。本文講清專案結構到匯出的全流程。
Writing E-books / EPUB in Markdown: Self-Publishing & Layout Basics
Want to self-publish a small book, a tutorial collection, or a docs manual? Write the body in Markdown and let a tool convert it to EPUB/MOBI with one click—far less hassle than wrestling with layout in Word. This article covers the full flow from project structure to export.
一、为什么用 Markdown 写书
写书最大的痛是“排版”——章节、目录、页码、字体反复调。Markdown 让你先专注内容,把排版交给工具:
- 纯文本好版本化:每章一个
.md,Git 管理改动,误删可回滚。 - 一次写作多端发布:同一份源能转 EPUB(电子书)、PDF(打印)、HTML(网页)。
- 不被软件绑架:没有私有格式,换工具说走就走。
小技巧:先在 365Lab 编辑器 把每章写顺、预览满意,再合并进电子书项目,写作最稳。
二、一本电子书的项目结构
一个清晰的目录能省掉后面很多麻烦。典型结构如下:
my-book/
├── metadata.yml # 书名、作者、语言等
├── cover.jpg # 封面图
├── chapter-01.md # 第一章
├── chapter-02.md # 第二章
└── README.md # 简介
metadata.yml 里放书名、作者、语言、标识符,转换工具会把它写进 EPUB 的“元信息”,阅读器才能正确显示书名和作者。
三、三种转换方案
1. Pandoc —— 万能转换器
pandoc chapter-*.md -o book.epub 一行就能把多篇 Markdown 合成 EPUB。支持目录、封面、样式,是技术作者的首选。
2. mdBook —— 专注“书”
Rust 写的电子书/文档框架,自带目录导航和阅读界面,适合教程、手册类书籍,输出既可以是网页也可以是 EPUB。
3. Typora / 编辑器导出
部分编辑器支持“导出为 EPUB”,适合单本小书、不想碰命令行的人。和 Markdown 转 PDF、转 Word 同一套导出思路。
| 方案 | 命令行 | 适合 | 额外能力 |
|---|---|---|---|
| Pandoc | 需要 | 通用/技术书 | 格式最全 |
| mdBook | 需要 | 教程/手册 | 网页+电子书 |
| Typora 导出 | 不需要 | 单本小书 | 所见即所得 |
四、从写作到 EPUB 的步骤
- 分章写:每章一个
.md,用#写章标题。 - 加元信息:准备
metadata.yml与封面图。 - 合并导出:
pandoc chapter-*.md metadata.yml --epub-cover-image=cover.jpg -o book.epub。 - 校验:用阅读器(如 Apple Books、Calibre)打开,检查目录跳转和封面。
五、目录、封面与样式
EPUB 的“目录”由标题层级自动生成,所以规范使用 #/## 很重要。封面用一张图即可;想统一风格,可以写一段 CSS 控制正文字体、行距、标题样式。
想要打印版或给编辑的定稿,可同步导出 PDF;需要 docx 给出版社,见 Markdown 转 Word。简历类单篇排版可参考 用 Markdown 写简历。
六、常见问题
Q:EPUB 和 PDF 该用哪个?
A:EPUB 适合在手机/阅读器上流式阅读、能调字体;PDF 适合定稿打印、版面固定。两者都能从 Markdown 生成。
Q:Kindle 能看吗?
A:能。EPUB 可用 Calibre 转成 MOBI/AZW3 推送到 Kindle。
Q:图片怎么处理?
A:把图放进项目文件夹,用相对路径引用(写法见 Markdown 插入图片),转换时会一起打包进 EPUB。
Q:需要会编程吗?
A:用 Typora 这类编辑器导出完全不用;Pandoc/mdBook 才需要一点命令行。
先把 Markdown 基础打牢,看 Markdown 入门;格式转换细节见 转 PDF 与 转 Word;做网页版可参考 导出 HTML。
一、為什麼用 Markdown 寫書
寫書最大的痛是「排版」——章節、目錄、頁碼、字體反覆調。Markdown 讓你先專注內容,把排版交給工具:
- 純文字好版本化:每章一個
.md,Git 管理改動,誤刪可回滾。 - 一次寫作多端發布:同一份源能轉 EPUB(電子書)、PDF(列印)、HTML(網頁)。
- 不被軟體綁架:沒有私有格式,換工具說走就走。
小技巧:先在 365Lab 編輯器 把每章寫順、預覽滿意,再合併進電子書專案,寫作最穩。
二、一本電子書的專案結構
一個清晰的目錄能省掉後面很多麻煩。典型結構如下:
my-book/
├── metadata.yml # 書名、作者、語言等
├── cover.jpg # 封面圖
├── chapter-01.md # 第一章
├── chapter-02.md # 第二章
└── README.md # 簡介
metadata.yml 裡放書名、作者、語言、識別碼,轉換工具會把它寫進 EPUB 的「元資訊」,閱讀器才能正確顯示書名和作者。
三、三種轉換方案
1. Pandoc —— 萬能轉換器
pandoc chapter-*.md -o book.epub 一行就能把多篇 Markdown 合成 EPUB。支援目錄、封面、樣式,是技術作者的首選。
2. mdBook —— 專注「書」
Rust 寫的電子書 / 文件框架,自帶目錄導覽和閱讀介面,適合教學、手冊類書籍,輸出既可以是網頁也可以是 EPUB。
3. Typora / 編輯器匯出
部分編輯器支援「匯出為 EPUB」,適合單本小書、不想碰命令列的人。和 Markdown 轉 PDF、轉 Word 同一套匯出思路。
| 方案 | 命令列 | 適合 | 額外能力 |
|---|---|---|---|
| Pandoc | 需要 | 通用 / 技術書 | 格式最全 |
| mdBook | 需要 | 教學 / 手冊 | 網頁 + 電子書 |
| Typora 匯出 | 不需要 | 單本小書 | 所見即所得 |
四、從寫作到 EPUB 的步驟
- 分章寫:每章一個
.md,用#寫章標題。 - 加元資訊:準備
metadata.yml與封面圖。 - 合併匯出:
pandoc chapter-*.md metadata.yml --epub-cover-image=cover.jpg -o book.epub。 - 校驗:用閱讀器(如 Apple Books、Calibre)開啟,檢查目錄跳轉和封面。
五、目錄、封面與樣式
EPUB 的「目錄」由標題層級自動生成,所以規範使用 #/## 很重要。封面用一張圖即可;想統一風格,可以寫一段 CSS 控制正文字體、行距、標題樣式。
想要列印版或給編輯的定稿,可同步匯出 PDF;需要 docx 給出版社,見 Markdown 轉 Word。履歷類單篇排版可參考 用 Markdown 寫履歷。
六、常見問題
Q:EPUB 和 PDF 該用哪個?
A:EPUB 適合在手機 / 閱讀器上流式閱讀、能調字體;PDF 適合定稿列印、版面固定。兩者都能從 Markdown 產生。
Q:Kindle 能看嗎?
A:能。EPUB 可用 Calibre 轉成 MOBI/AZW3 推送到 Kindle。
Q:圖片怎麼處理?
A:把圖放進專案資料夾,用相對路徑引用(寫法見 Markdown 插入圖片),轉換時會一起打包進 EPUB。
Q:需要會程式設計嗎?
A:用 Typora 這類編輯器匯出完全不用;Pandoc/mdBook 才需要一點命令列。
先把 Markdown 基礎打牢,看 Markdown 入門;格式轉換細節見 轉 PDF 與 轉 Word;做網頁版可參考 匯出 HTML。
1. Why write books in Markdown
The biggest pain of writing a book is "layout"—chapters, tables of contents, page numbers, and fonts tweaked over and over. Markdown lets you focus on content first and hand layout to the tool:
- Plain text versioning: One
.mdper chapter, managed with Git, so accidental deletes can be rolled back. - Write once, publish anywhere: The same source converts to EPUB (e-book), PDF (print), and HTML (web).
- No software lock-in: No proprietary format—switch tools and walk away anytime.
Tip: First write each chapter in the 365Lab editor and preview until you're happy, then merge it into the e-book project for the most stable writing.
2. An e-book's project structure
A clear folder layout saves a lot of trouble later. A typical structure:
my-book/
├── metadata.yml # book title, author, language, etc.
├── cover.jpg # cover image
├── chapter-01.md # chapter one
├── chapter-02.md # chapter two
└── README.md # intro
Inside metadata.yml you put the title, author, language, and identifier; the converter writes it into the EPUB's "metadata" so readers can correctly display the book title and author.
3. Three conversion options
1. Pandoc — the universal converter
pandoc chapter-*.md -o book.epub merges multiple Markdown files into an EPUB in one line. It supports TOC, cover, and styling, and is the go-to for technical authors.
2. mdBook — focused on "books"
A Rust-based e-book / docs framework with built-in TOC navigation and a reading interface, suiting tutorials and manuals; its output can be either web pages or EPUB.
3. Typora / editor export
Some editors support "export to EPUB," suiting single small books and people who'd rather avoid the command line. It shares the same export mindset as Markdown to PDF and to Word.
| Option | Command line | Best for | Extra |
|---|---|---|---|
| Pandoc | Required | General / technical books | Most formats |
| mdBook | Required | Tutorials / manuals | Web + e-book |
| Typora export | Not needed | Single small book | WYSIWYG |
4. From writing to EPUB
- Write by chapter: One
.mdper chapter, with#for the chapter title. - Add metadata: Prepare
metadata.ymland a cover image. - Merge & export:
pandoc chapter-*.md metadata.yml --epub-cover-image=cover.jpg -o book.epub. - Verify: Open it in a reader (e.g., Apple Books, Calibre) and check TOC jumps and the cover.
5. TOC, cover & styling
An EPUB's "table of contents" is generated automatically from heading levels, so using #/## consistently matters. A single image is enough for the cover; to unify the style, you can write a bit of CSS to control body font, line spacing, and heading styles.
For a print version or a final draft for your editor, export PDF in parallel; if you need docx for a publisher, see Markdown to Word. For single-page résumé layout, refer to Writing a résumé in Markdown.
6. FAQ
Q: Should I use EPUB or PDF?
A: EPUB suits streaming reading on phones/readers and lets you adjust fonts; PDF suits final print with fixed layout. Both can be generated from Markdown.
Q: Can Kindle read it?
A: Yes. You can use Calibre to convert EPUB into MOBI/AZW3 and send it to your Kindle.
Q: How are images handled?
A: Put images in the project folder and reference them with relative paths (see Inserting Images in Markdown); they get packaged into the EPUB during conversion.
Q: Do I need to know programming to write an e-book?
A: Exporting with an editor like Typora needs none; only Pandoc/mdBook need a little command line.
To nail the Markdown basics first, see Markdown Basics; for conversion details, see to PDF and to Word; for a web version, refer to Exporting HTML.