ebook:title: “AsciiDoc 生成电子书完整教程”authors: [“lijs”]language: “zh-CN”cover: “path/to/cover.jpg”pubdate: “2026年5月19日”文章目录cover: path/to/cover.jpgpubdate: 2026年5月19日AsciiDoc 生成电子书完整教程一、为什么选择 AsciiDoc 写电子书二、环境准备2.1 安装 Ruby 环境2.2 安装 Asciidoctor 核心工具2.3 安装 PDF 生成插件2.4 安装电子书生成工具三、电子书项目结构四、文档头配置书级别设置五、章节划分与结构5.1 书籍特有结构5.2 分页控制5.3 节内链接六、生成 PDF 电子书6.1 基础命令6.2 带属性的命令6.3 自定义 PDF 主题6.4 封面图片七、生成 EPUB 电子书7.1 安装 EPUB3 插件7.2 生成 EPUB7.3 EPUB 专用配置7.4 封面图设置EPUB八、生成 MOBIKindle格式8.1 方法一先 EPUB 后转换8.2 方法二使用 git-scribe九、使用 Maven 自动构建十、从 Markdown 迁移十一、完整示例book.adoc 完整示例生成命令十二、常见问题Q1: 中文显示乱码Q2: 目录不显示Q3: EPUB 在 Kindle 上格式错乱Q4: 代码块语法高亮不生效十三、总结中文竖排、古籍排版 第一步搭建中文排版环境1. 准备中文字体2. 创建支持中文的主题文件YAML3. 引用主题并生成 PDF 第二步实现古籍风格的竖排Vertical Writing方法一CSS 逻辑适合用作局部引用方法二page 逻辑适合整书竖排 - 进阶方案 第三步古籍韵味细节打磨1. 添加竖排分隔线装订线2. 竖排中的插图处理3. 使用深色模式与旧纸背景 总结与工作流建议3. 使用深色模式与旧纸背景 总结与工作流建议AsciiDoc 生成电子书完整教程使用 AsciiDoc 生成电子书EPUB/MOBI/PDF是一个非常成熟的工作流。AsciiDoc 本身就是为写书而设计的标记语言配合 Asciidoctor 工具链可以一次写作多格式出版。一、为什么选择 AsciiDoc 写电子书特性说明单一源文件一份.adoc文档同时生成 EPUB、PDF、MOBI、HTML版本控制友好纯文本格式可直接用 Git 管理支持 diff 和协作专业排版自动生成目录、页码、页眉页脚、章节编号丰富的扩展支持数学公式、图表Mermaid/PlantUML、代码高亮标准化语法由 Eclipse Foundation 维护避免方言问题二、环境准备2.1 安装 Ruby 环境Asciidoctor 基于 Ruby 开发需要先安装 Ruby。macOSbrewinstallrubyLinux (Ubuntu/Debian)sudoapt-getinstallruby-fullWindows下载安装 RubyInstaller安装时勾选 “Add Ruby to PATH”验证安装ruby--version2.2 安装 Asciidoctor 核心工具geminstallasciidoctor2.3 安装 PDF 生成插件geminstallasciidoctor-pdf2.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: zhangexample.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这会自动启用书籍专用功能 完整的书籍标题: 副标题 张三 zhangexample.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.adoc6.2 带属性的命令asciidoctor-pdf\-arevnumberv2.0\-arevdate2024-01-15\-adocinfoshared\-ooutput/book.pdf\book.adoc6.3 自定义 PDF 主题创建themes/book-theme.ymlextends: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-themebook-theme\-apdf-themesdirthemes\-ooutput/book.pdf\book.adoc6.4 封面图片:cover-image: images/cover.png七、生成 EPUB 电子书7.1 安装 EPUB3 插件geminstallasciidoctor-epub37.2 生成 EPUBasciidoctor-epub3 book.adoc-ooutput/book.epub7.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八、生成 MOBIKindle格式8.1 方法一先 EPUB 后转换# 生成 EPUBasciidoctor-epub3 book.adoc-ooutput/book.epub# 使用 KindleGen 转换kindlegen output/book.epub-obook.mobi# 或使用 Calibreebook-convert output/book.epub output/book.mobi8.2 方法二使用 git-scribegitscribe init my-bookcdmy-book# 编写 book.ascgitscribe gen mobi# 生成 MOBIgitscribe gen epub# 生成 EPUBgitscribe gen pdf# 生成 PDFgitscribe gen all# 生成全部格式九、使用 Maven 自动构建对于团队协作或 CI/CD 场景可以使用 Maven 插件自动化生成pom.xml 配置plugingroupIdorg.asciidoctor/groupIdartifactIdasciidoctor-maven-plugin/artifactIdversion2.2.0/versionconfigurationsourceDirectorysrc/docs/asciidoc/sourceDirectoryoutputDirectorytarget/docs/asciidoc/outputDirectorybackendpdf/backenddoctypebook/doctypeattributespdf-stylesdir${project.basedir}/src/themes/pdf-stylesdirpdf-stylecustom/pdf-styletoc/sectnums//attributes/configuration/plugin运行生成mvn generate-resources十、从 Markdown 迁移如果你已有 Markdown 格式的书籍可以使用 Pandoc 转换pandoc book.md-obook.adoc手动调整标题#→代码块→[source,language]----添加:doctype: book十一、完整示例book.adoc 完整示例 AsciiDoc 电子书完全指南: 从入门到出版 张三 zhangexample.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.mobiechoAll formats generated in output/十二、常见问题Q1: 中文显示乱码需要配置中文字体。在主题 YAML 中添加font:catalog:NotoSansCJK:normal:/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttcQ2: 目录不显示确保设置了:toc:和:doctype: book。Q3: EPUB 在 Kindle 上格式错乱Kindle 对 EPUB3 支持有限建议先转 MOBI 格式。Q4: 代码块语法高亮不生效安装 pygments 或 rougegeminstallrouge然后在文档头添加:source-highlighter: rouge十三、总结AsciiDoc Asciidoctor 是一套完整的电子书出版方案格式命令适用场景PDFasciidoctor-pdf打印、正式出版EPUBasciidoctor-epub3电子书阅读器Apple Books、KoboMOBIkindlegen EPUBKindle 设备HTMLasciidoctor在线文档核心工作流用.adoc格式写作设置:doctype: book使用include::拆分章节通过主题自定义样式用不同命令生成各格式电子书如需更详细的主题定制如中文竖排、古籍排版或自动化构建流程可以继续深入探讨。中文竖排、古籍排版没问题。从“基础工具使用”深入到“专业书籍排版”才算真正触及 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 CJK3. 引用主题并生成 PDF使用命令行应用主题asciidoctor-pdf-apdf-themecn-book-theme.yml-apdf-fontsdir.-ascriptscjk my-book.adocpdf-theme指定刚才创建的 YAML 文件。pdf-fontsdir.告诉程序在当前目录下寻找fonts文件夹。scriptscjk这是一个极其关键的选项它会强制启用 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:22. 在 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-rl2. 在 AsciiDoc 中强制应用页面虽然 Asciidoctor PDF 原生不支持在文档中间直接切换页面模板但你可以通过pass宏块嵌入原始的 PDF 指令来强制换页并切换版式。 第一章现代诗歌 这里是横向内容。 pass:[rack sheet-sizeA4 writing-modevertical-rl directionrtl] 第二章古诗鉴赏 这里的所有内容都会变成从右向左的竖排文字连标点符号的间距和位置都会自动调整。很适合展示你的格律诗作品。 pass:[rack sheet-sizeA4 writing-modehorizontal directionltr] 第三章回到横向 继续写现代内容。(注意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:102. 竖排中的插图处理在竖排文档中插入图片需要仔细调整。古籍插图常以“对开”或“单页”形式出现。你可以通过添加pdfwidth属性来控制图片在竖排版面中的大小。[.vertical-text] **** // 插入一幅画指定宽度为版心的 60%并居中 image::path/to/your/drawing.png[pdfwidth60%, aligncenter] 这 是 题 画 诗 ****3. 使用深色模式与旧纸背景为了追求视觉上的古韵可以给你的 PDF 添加一个类似宣纸的背景。1. 准备一张宣纸背景图rice-paper.png。2. 在主题文件中添加页面背景# 在 cn-book-theme.yml 中添加page:background_color:#fbf7e9 # 米黄色底色# 或者使用背景图片background_image:image:rice-paper.png[positioncenter,repeatno-repeat,pdfwidth100%]这样生成的 PDF 不仅文字是竖排的连视觉底色也具有古书的质感。 总结与工作流建议从“字体”和scriptscjk参数开始这是最基础的保障。利用role角色控制局部竖排为特定段落加个标记就能实现竖排不会影响全局。谨慎使用page direction整书竖排的配置要求比较高建议先在单独的实验文档中配置成功后再应用到主项目。善用页眉页脚营造氛围通过修改页眉页脚的文字和内容能极大地增强古籍的视觉感受。整。古籍插图常以“对开”或“单页”形式出现。你可以通过添加pdfwidth属性来控制图片在竖排版面中的大小。[.vertical-text] **** // 插入一幅画指定宽度为版心的 60%并居中 image::path/to/your/drawing.png[pdfwidth60%, aligncenter] 这 是 题 画 诗 ****3. 使用深色模式与旧纸背景为了追求视觉上的古韵可以给你的 PDF 添加一个类似宣纸的背景。1. 准备一张宣纸背景图rice-paper.png。2. 在主题文件中添加页面背景# 在 cn-book-theme.yml 中添加page:background_color:#fbf7e9 # 米黄色底色# 或者使用背景图片background_image:image:rice-paper.png[positioncenter,repeatno-repeat,pdfwidth100%]这样生成的 PDF 不仅文字是竖排的连视觉底色也具有古书的质感。 总结与工作流建议从“字体”和scriptscjk参数开始这是最基础的保障。利用role角色控制局部竖排为特定段落加个标记就能实现竖排不会影响全局。谨慎使用page direction整书竖排的配置要求比较高建议先在单独的实验文档中配置成功后再应用到主项目。善用页眉页脚营造氛围通过修改页眉页脚的文字和内容能极大地增强古籍的视觉感受。如果你在配置中遇到了字体识别失败、竖排方向不对或者页码格式调整的问题随时可以把你的主题文件发给我我们一起看看。
