asciidoc 如何生成电子书 详细教程

ebook:
title: “AsciiDoc 生成电子书完整教程”
authors: [“lijs”]
language: “zh-CN”

cover: “path/to/cover.jpg”

pubdate: “2026年5月19日”

AsciiDoc 生成电子书完整教程

使用 AsciiDoc 生成电子书（EPUB/MOBI/PDF）是一个非常成熟的工作流。AsciiDoc 本身就是为写书而设计的标记语言，配合 Asciidoctor 工具链，可以"一次写作，多格式出版"。

一、为什么选择 AsciiDoc 写电子书？

二、环境准备

2.1 安装 Ruby 环境

Asciidoctor 基于 Ruby 开发，需要先安装 Ruby。

macOS：

brewinstallruby

Linux (Ubuntu/Debian)：

sudoapt-getinstallruby-full

Windows：

• 下载安装 RubyInstaller
• 安装时勾选 “Add Ruby to PATH”

验证安装：

ruby--version

2.2 安装 Asciidoctor 核心工具

geminstallasciidoctor

2.3 安装 PDF 生成插件

geminstallasciidoctor-pdf

2.4 安装电子书生成工具

生成 EPUB 和 MOBI 需要额外工具：

# 安装 EPUB 生成依赖geminstallasciidoctor-epub3# 安装 KindleGen（用于生成 MOBI）# macOS:brewinstallkindlegen# Linux: 从 Amazon 官网下载 kindlegen 并放入 PATH# 或使用 calibre 的 ebook-convert 替代

或使用一体化工具 git-scribe（专门用于电子书写作）：

geminstallgit-scribe

三、电子书项目结构

一个规范的电子书项目建议采用以下目录结构：

my-book/ ├── book.adoc # 主文档（入口文件） ├── chapters/ # 各章节文件 │ ├── preface.adoc │ ├── chapter1.adoc │ ├── chapter2.adoc │ └── appendix.adoc ├── images/ # 图片资源 │ ├── cover.png │ └── diagram.png ├── themes/ # PDF 主题文件 │ └── custom-theme.yml └── output/ # 生成物输出目录

使用 include 指令组织多文件：

= 我的第一本电子书 :author: 张三 :email: zhang@example.com :revdate: 2024-01-01 :toc: :toclevels: 3 :sectnums: // 前言 include::chapters/preface.adoc[] == 第一章：基础概念 include::chapters/chapter1.adoc[] == 第二章：深入理解 include::chapters/chapter2.adoc[] // 附录 include::chapters/appendix.adoc[]

四、文档头配置（书级别设置）

电子书需要在文档头设置:doctype: book，这会自动启用书籍专用功能：

= 完整的书籍标题: 副标题 张三 <zhang@example.com> :revnumber: v1.0 :revdate: 2024-01-01 :revremark: 初版 // 关键设置：指定为书籍类型 :doctype: book // 目录设置 :toc: // 生成目录 :toclevels: 3 // 目录显示到第3级标题 :toc-title: 目录 // 目录标题（中文） // 章节编号 :sectnums: // 启用章节编号 :sectnumlevels: 4 // 编号深度 :sectlinks: // 目录链接可点击 :sectanchors: // 生成锚点 // 其他设置 :icons: font // 使用字体图标 :lang: zh // 语言设置 :listing-caption: 代码清单 :table-caption: 表 :figure-caption: 图

设置:doctype: book后，Asciidoctor 会自动生成：

• 标题页
• 目录
• 正文起始页
• 章节自动分页

五、章节划分与结构

5.1 书籍特有结构

= 完整指南 :doctype: book // 前言（无编号） [preface] == 前言 这是前言内容... // 正文开始（自动从第一章编号） == 第一部分：基础知识 === 第一章：入门 内容... === 第二章：进阶 内容... == 第二部分：高级主题 === 第三章：深入 内容... // 附录（使用 Appendix 样式） [appendix] == 附录A：配置参考 // 参考文献 [bibliography] == 参考文献 - [[[ref1]]] 作者. 书名. 出版社, 2024.

5.2 分页控制

// 强制分页 <<< // 在目录后分页，让正文从新页开始 :toc: <<< = 第一章标题

5.3 节内链接

[[ch01]] == 第一章 关于这个主题的详细讨论，请参见 <<ch01,第一章>>。

六、生成 PDF 电子书

6.1 基础命令

asciidoctor-pdf book.adoc-ooutput/book.pdf

如果使用标准 asciidoctor 命令：

asciidoctor-rasciidoctor-pdf-bpdf-ooutput/book.pdf book.adoc

6.2 带属性的命令

asciidoctor-pdf\-arevnumber="v2.0"\-arevdate="2024-01-15"\-adocinfo=shared\-ooutput/book.pdf\book.adoc

6.3 自定义 PDF 主题

创建themes/book-theme.yml：

extends:defaultpage:size:A4margin:[0.75in,1in,0.75in,1in]# 页眉配置header:height:0.5inline_height:1recto_content:center:'{document-title}'verso_content:center:'{document-title}'# 页脚配置footer:height:0.5inline_height:1recto_content:right:'{chapter-title} | *{page-number}*'verso_content:left:'*{page-number}* | {chapter-title}'# 字体配置（中文支持）font:catalog:NotoSansCJK:normal:NotoSansCJKsc-Regular.otfbold:NotoSansCJKsc-Bold.otffallbacks:[NotoSansCJK]# 封面配置cover:front:image:image:images/cover.png[]

应用主题：

asciidoctor-pdf\-apdf-theme=book-theme\-apdf-themesdir=themes\-ooutput/book.pdf\book.adoc

6.4 封面图片

:cover-image: images/cover.png

七、生成 EPUB 电子书

7.1 安装 EPUB3 插件

geminstallasciidoctor-epub3

7.2 生成 EPUB

asciidoctor-epub3 book.adoc-ooutput/book.epub

7.3 EPUB 专用配置

= 我的电子书 :doctype: book // EPUB 专用设置 :ebook-format: epub3 :epub3-guide: nav :epub3-preferred: true :epub3-vertical-writing: // 竖排文字（日文/中文）

7.4 封面图设置（EPUB）

:epub-cover-image: images/cover.png

八、生成 MOBI（Kindle）格式

8.1 方法一：先 EPUB 后转换

# 生成 EPUBasciidoctor-epub3 book.adoc-ooutput/book.epub# 使用 KindleGen 转换kindlegen output/book.epub-obook.mobi# 或使用 Calibreebook-convert output/book.epub output/book.mobi

8.2 方法二：使用 git-scribe

gitscribe init my-bookcdmy-book# 编写 book.ascgitscribe gen mobi# 生成 MOBIgitscribe gen epub# 生成 EPUBgitscribe gen pdf# 生成 PDFgitscribe gen all# 生成全部格式

九、使用 Maven 自动构建

对于团队协作或 CI/CD 场景，可以使用 Maven 插件自动化生成：

pom.xml 配置：

<plugin><groupId>org.asciidoctor</groupId><artifactId>asciidoctor-maven-plugin</artifactId><version>2.2.0</version><configuration><sourceDirectory>src/docs/asciidoc</sourceDirectory><outputDirectory>target/docs/asciidoc</outputDirectory><backend>pdf</backend><doctype>book</doctype><attributes><pdf-stylesdir>${project.basedir}/src/themes</pdf-stylesdir><pdf-style>custom</pdf-style><toc/><sectnums/></attributes></configuration></plugin>

运行生成：

mvn generate-resources

十、从 Markdown 迁移

如果你已有 Markdown 格式的书籍，可以：

1. 使用 Pandoc 转换：

pandoc book.md-obook.adoc

2. 手动调整：
   • 标题：#→=
   • 代码块：`````→[source,language]+----
   • 添加:doctype: book

十一、完整示例

book.adoc 完整示例

= AsciiDoc 电子书完全指南: 从入门到出版 张三 <zhang@example.com> :revnumber: v1.0.0 :revdate: 2024-01-15 // 书籍配置 :doctype: book :lang: zh :icons: font // 目录配置 :toc: :toclevels: 3 :toc-title: 目录 // 编号配置 :sectnums: :sectnumlevels: 4 :sectlinks: :sectanchors: // 封面 :cover-image: images/cover.png // 前言 [preface] == 为什么写这本书 在当今信息爆炸的时代... // 正文开始 == 第一部分：基础篇 === 为什么选择 AsciiDoc AsciiDoc 相比 Markdown 的优势... === 环境搭建 ==== 安装 Ruby ==== 安装 Asciidoctor == 第二部分：进阶篇 === 自定义主题 [source,yaml] ---- page: size: A4 margin: [0.75in, 1in, 0.75in, 1in] ---- === 数学公式 stem:[E = mc^2] // 附录 [appendix] == 附录A：命令速查表 |=== | 命令 | 说明 | asciidoctor-pdf doc.adoc | 生成 PDF | asciidoctor-epub3 doc.adoc | 生成 EPUB |=== // 参考文献 [bibliography] == 参考文献 - [[[asciidoc-guide]]] Asciidoctor 官方文档. https://docs.asciidoctor.org

生成命令

# 生成 PDFasciidoctor-pdf book.adoc-ooutput/book.pdf# 生成 EPUBasciidoctor-epub3 book.adoc-ooutput/book.epub# 一键生成所有格式（使用脚本）#!/bin/bashmkdir-poutput asciidoctor-pdf book.adoc-ooutput/book.pdf asciidoctor-epub3 book.adoc-ooutput/book.epub kindlegen output/book.epub-ooutput/book.mobiecho"All formats generated in output/"

十二、常见问题

Q1: 中文显示乱码

需要配置中文字体。在主题 YAML 中添加：

font:catalog:NotoSansCJK:normal:/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc

Q2: 目录不显示

确保设置了:toc:和:doctype: book。

Q3: EPUB 在 Kindle 上格式错乱

Kindle 对 EPUB3 支持有限，建议先转 MOBI 格式。

Q4: 代码块语法高亮不生效

安装 pygments 或 rouge：

geminstallrouge

然后在文档头添加：

:source-highlighter: rouge

十三、总结

AsciiDoc + Asciidoctor 是一套完整的电子书出版方案：

核心工作流：

1. 用.adoc格式写作，设置:doctype: book
2. 使用include::拆分章节
3. 通过主题自定义样式
4. 用不同命令生成各格式电子书

如需更详细的主题定制（如中文竖排、古籍排版）或自动化构建流程，可以继续深入探讨。

中文竖排、古籍排版

没问题。从“基础工具使用”深入到“专业书籍排版”，才算真正触及 AsciiDoc 的强大之处。中文竖排和古籍排版，本质上是将 AsciiDoc 强大的PDF 主题定制能力（Theming System）和CJK（中日韩）文字排版特性相结合。

下面我们来深入探讨如何实现这些效果。

📜 第一步：搭建中文排版环境

想要排版古籍或实现优雅的中文竖排，首先必须解决中文正常显示的问题。

1. 准备中文字体

Asciidoctor PDF 默认使用的字体不包含中文字符，我们需要自己准备。推荐使用Noto Sans CJK（思源黑体）或Source Han Serif（思源宋体），两者都是开源且高质量的字体。

你可以在 Google Noto Fonts 或 GitHub 上下载.ttf格式的字体文件。下载后，在项目根目录下创建一个fonts文件夹来存放它们。

2. 创建支持中文的主题文件（YAML）

创建一个新的主题文件，命名为cn-book-theme.yml。这个文件会告诉转换器使用你指定的中文字体。

# cn-book-theme.ymlextends:defaultpage:size:A4# 古籍排版常用的天头地脚比例，这里可以自定义margin:[2.2in,1.2in,1.8in,1.2in]font:catalog:# 注册你的中文字体Noto Serif CJK:normal:fonts/NotoSerifCJKsc-Regular.otfbold:fonts/NotoSerifCJKsc-Bold.otfitalic:fonts/NotoSerifCJKsc-Regular.otfbold_italic:fonts/NotoSerifCJKsc-Bold.otf# 注册一个等宽字体用于代码块Noto Sans Mono CJK:normal:fonts/NotoSansMonoCJKsc-Regular.otf# 设置字体回退，避免某些特殊字符缺失fallbacks:[Noto Serif CJK]base:font-family:Noto Serif CJK# 关键点：取消默认的双端对齐，特别是中英文混排时，左对齐更自然text-align:leftfont-size:11line-height-length:20font-color:#222222# 标题字体稍微加粗或加大heading:font-family:Noto Serif CJKfont-color:#000000font-style:boldcode:font-family:Noto Sans Mono CJK

3. 引用主题并生成 PDF

使用命令行应用主题：

asciidoctor-pdf-apdf-theme=cn-book-theme.yml-apdf-fontsdir=.-ascripts=cjk my-book.adoc

• pdf-theme：指定刚才创建的 YAML 文件。
• pdf-fontsdir=.：告诉程序在当前目录下寻找fonts文件夹。
• scripts=cjk：这是一个极其关键的选项！它会强制启用 CJK 换行规则，允许中文在任意字符后换行，而不是像英文那样必须在单词边界换行，从而解决了中文字符串不换行的问题。

📜 第二步：实现古籍风格的竖排（Vertical Writing）

这是古籍排版的精髓。Asciidoctor PDF 本身对竖排的支持仍在演进，以下是目前最可行的两种方案。

方法一：CSS 逻辑（适合用作局部引用）

这种方法通过内联 CSS 或角色（role）来实现竖排，非常灵活。

1. 定义竖排样式

在cn-book-theme.yml中添加一个role（角色），用来给特定的文本块打标签。

# 在 cn-book-theme.yml 的末尾添加role:vertical-text:writing-mode:vertical-rltext-orientation:mixedfont-size:14line-height:2

2. 在 AsciiDoc 文档中使用

使用[.vertical-text]标记来包裹需要竖排的内容。这非常适合处理书名、对联或题词。

[.vertical-text] **** 靜 以 修 身 俭 以 养 德 ****

这个角色会将普通文本块旋转为从右向左、从上到下的竖排布局。

方法二：@page逻辑（适合整书竖排 - 进阶方案）

如果你想实现整本书，或者整个章节都是竖排（例如诗集），可以尝试下面的方式。请注意，这是一个实验性的进阶技巧，需要你的 Asciidoctor PDF 版本比较新。

1. 在主题文件中定义竖排页面

# 在 cn-book-theme.yml 中定义page:size:A4layout:portrait# 定义竖排页面的方向，从右往左翻direction:rtlvertical-page:size:A4layout:portraitdirection:rtlwriting-mode:vertical-rl

2. 在 AsciiDoc 中强制应用页面

虽然 Asciidoctor PDF 原生不支持在文档中间直接切换页面模板，但你可以通过pass宏块嵌入原始的 PDF 指令来强制换页并切换版式。

== 第一章：现代诗歌 这里是横向内容。 <<< pass:[<rack sheet-size="A4" writing-mode="vertical-rl" direction="rtl">] == 第二章：古诗鉴赏 这里的所有内容都会变成从右向左的竖排文字，连标点符号的间距和位置都会自动调整。很适合展示你的格律诗作品。 <<< pass:[<rack sheet-size="A4" writing-mode="horizontal" direction="ltr">] == 第三章：回到横向 继续写现代内容。

(注意：pass宏的具体指令可能随版本更新，建议查阅最新的 Asciidoctor PDF 文档)。

📜 第三步：古籍韵味细节打磨

有了竖排文字和合适的字体，我们还差最后一步：整体的古籍“味道”。

1. 添加竖排分隔线（装订线）

古籍通常会有“鱼尾”或版心线。我们可以通过自定义页眉页脚来模拟。

# 在 cn-book-theme.yml 中修改 header/footerheader:height:1.5inline_height:1recto:# 模拟古籍卷轴顶部的装饰线center:content:'      'font-size:14font-color:#8B0000# 左侧显示章节名left:content:'{chapter-title}'font-size:9footer:height:1.2inrecto:# 右侧显示页码，模拟“第X卷”right:content:'第 {page-number} 卷'font-size:10

2. 竖排中的插图处理

在竖排文档中插入图片需要仔细调整。古籍插图常以“对开”或“单页”形式出现。你可以通过添加pdfwidth属性来控制图片在竖排版面中的大小。

[.vertical-text] **** // 插入一幅画，指定宽度为版心的 60%，并居中 image::path/to/your/drawing.png[pdfwidth=60%, align=center] 这 是 题 画 诗 ****

3. 使用深色模式与旧纸背景

为了追求视觉上的古韵，可以给你的 PDF 添加一个类似宣纸的背景。

1. 准备一张宣纸背景图（rice-paper.png）。

2. 在主题文件中添加页面背景：

# 在 cn-book-theme.yml 中添加page:background_color:#fbf7e9 # 米黄色底色# 或者使用背景图片background_image:image:rice-paper.png[position=center,repeat=no-repeat,pdfwidth=100%]

这样生成的 PDF 不仅文字是竖排的，连视觉底色也具有古书的质感。

💎 总结与工作流建议

1. 从“字体”和scripts=cjk参数开始：这是最基础的保障。
2. 利用role角色控制局部竖排：为特定段落加个标记就能实现竖排，不会影响全局。
3. 谨慎使用page direction：整书竖排的配置要求比较高，建议先在单独的实验文档中配置成功后再应用到主项目。
4. 善用页眉页脚营造氛围：通过修改页眉页脚的文字和内容，能极大地增强古籍的视觉感受。

整。古籍插图常以“对开”或“单页”形式出现。你可以通过添加pdfwidth属性来控制图片在竖排版面中的大小。

[.vertical-text] **** // 插入一幅画，指定宽度为版心的 60%，并居中 image::path/to/your/drawing.png[pdfwidth=60%, align=center] 这 是 题 画 诗 ****

3. 使用深色模式与旧纸背景

为了追求视觉上的古韵，可以给你的 PDF 添加一个类似宣纸的背景。

1. 准备一张宣纸背景图（rice-paper.png）。

2. 在主题文件中添加页面背景：

# 在 cn-book-theme.yml 中添加page:background_color:#fbf7e9 # 米黄色底色# 或者使用背景图片background_image:image:rice-paper.png[position=center,repeat=no-repeat,pdfwidth=100%]

这样生成的 PDF 不仅文字是竖排的，连视觉底色也具有古书的质感。

💎 总结与工作流建议

1. 从“字体”和scripts=cjk参数开始：这是最基础的保障。
2. 利用role角色控制局部竖排：为特定段落加个标记就能实现竖排，不会影响全局。
3. 谨慎使用page direction：整书竖排的配置要求比较高，建议先在单独的实验文档中配置成功后再应用到主项目。
4. 善用页眉页脚营造氛围：通过修改页眉页脚的文字和内容，能极大地增强古籍的视觉感受。

如果你在配置中遇到了字体识别失败、竖排方向不对或者页码格式调整的问题，随时可以把你的主题文件发给我，我们一起看看。