1. 摘要

本书是 AsciiDoc book 的常见结构标本。它集中展示前置内容、正文分部、章节层级、附录、术语表、参考资料和索引在书稿中的位置及组合规则。

本书用于学习常见结构组合，不作为日常新书的复制起点。

版本说明

本文档属于 AsciiDoc 多本书工作区示例。colophon 位于书籍前置区域，记录版本、来源或出版信息。

示例版本：v0.1。

献辞

献给每一位需要把书稿结构先想清楚再开始写作的人。

前言

这本标本书按结构位置组织，而不是按主题展开。阅读时先看 book.adoc，再对照各个被 include 的文件。

读者可以观察结构位置，再按实际书稿需要选择进入自己书中的结构。实际书稿的结构清单由写作目标、读者任务和发布边界决定；本书展示结构位置和组合关系，不作为必选清单。

日常写作起点可以参考样本 01-starter-book。

致谢

感谢 Asciidoctor 文档提供稳定术语和结构坐标。

第一部：前置结构

本部展示一本书进入正文之前的结构位置。摘要、版本说明、献辞、前言和致谢都属于书籍前置内容。

2. 前置内容地图

前置内容用于建立读者进入正文之前需要知道的说明、来源和阅读位置。

方括号中的名称是 section style。它作用于紧随其后的 section；当下一行是 include 指令时，style 作用于被 include 文件中的 section 标题。

结构职责

结构	职责
`[abstract]`	说明整本书覆盖什么。
`[colophon]`	记录版本、出版或来源信息。
`[dedication]`	放置献辞。
`[preface]`	说明写作目的和阅读方式。
`[acknowledgments]`	放置致谢。

[abstract]

说明整本书覆盖什么。

[colophon]

记录版本、出版或来源信息。

[dedication]

放置献辞。

[preface]

说明写作目的和阅读方式。

[acknowledgments]

放置致谢。

第二部：正文结构

本部展示正文中的 part、chapter、section 和离散标题。part 组织同一本书内部的大分部。

3. 正文结构地图

part 是 book doctype 中 document title 之后的 level 0 section。level 1 section 通常形成 chapter；multipart book 中 chapter 位于 part 下，普通 book 中 chapter 可以直接位于 book 下。

本模板把每个 part 的源文件放在 parts/<part-id>/ 下。这个目录约定服务维护边界；part 本身由 book.adoc 中的 level 0 section 声明。

本书启用 :sectnums:。part 标题不占用 chapter 编号；part 下的 level 1 section 按 book.adoc 展开后的顺序形成连续 chapter 编号。

3.1. 小节层级

section 是 chapter 内部的层级单位。

离散标题

离散标题显示为标题样式，但不创建 section，不参与章节编号，也不进入目录。

4. 内联结构标记

内联结构标记用于给正文中的术语、路径、引用目标和索引入口提供稳定身份。它不改变 book 的章节层级，但会提高正文片段的可维护性和可检索性。

写法结构作用

写法	结构作用
`[#stable-anchor]`	声明稳定引用目标。
`正文结构地图`	引用同一文档内的稳定目标。
`term`	把正文中已经出现的词作为可见索引词。
	正文没有出现该词时，补充隐藏索引入口。
`inline role`	给术语片段提供语义身份。
`[.path]` + monospace path	给路径文本提供语义身份。
`AsciiDoc 多本书工作区示例`	引用共享属性，减少多处重复文本。

[#stable-anchor]

声明稳定引用目标。

正文结构地图

引用同一文档内的稳定目标。

term

把正文中已经出现的词作为可见索引词。

正文没有出现该词时，补充隐藏索引入口。

inline role

给术语片段提供语义身份。

[.path] + monospace path

给路径文本提供语义身份。

AsciiDoc 多本书工作区示例

引用共享属性，减少多处重复文本。

语义 inline role 提供结构身份；具体视觉效果取决于输出样式。本书使用 inline role 标记术语片段，使用 parts/02-body-structure/ 标记路径片段。

Appendix A: 附录 A：结构速查

写法含义

写法	含义
`= 书名`	Document title（文档标题）。在 book 文档类型中作为整本书标题。
`= 部标题`	Document title 之后的 Level 0 Section。在 book 文档类型中可作为 Part（部）。
`== 章`	Level 1 Section（一级章节）。在 book 文档类型中通常作为 Chapter（章）。
`=== 节`	Level 2 Section（二级章节 / 节）。
`==== 小节`	Level 3 Section（三级章节 / 小节）。
`===== 次小节`	Level 4 Section（四级章节）。
`====== 最底层级`	Level 5 Section（五级章节）。AsciiDoc 支持的最深层级。

= 书名

Document title（文档标题）。在 book 文档类型中作为整本书标题。

= 部标题

Document title 之后的 Level 0 Section。在 book 文档类型中可作为 Part（部）。

== 章

Level 1 Section（一级章节）。在 book 文档类型中通常作为 Chapter（章）。

=== 节

Level 2 Section（二级章节 / 节）。

==== 小节

Level 3 Section（三级章节 / 小节）。

===== 次小节

Level 4 Section（四级章节）。

====== 最底层级

Level 5 Section（五级章节）。AsciiDoc 支持的最深层级。

[appendix]、[glossary]、[bibliography] 和 [index] 是 section style。它们改变紧随其后 section 的语义；标题层级仍由 = 数量决定。

术语表

术语表通常使用定义列表记录术语和解释。

book: 具有独立 book.adoc、章节顺序和构建产物的书籍单位。
part: 同一本 book 内部的 level 0 大分部。
chapter: book 中的主要正文单位，通常使用 == 标题。
section: chapter 内部的层级标题。
appendix: 放置补充材料的后置章节。
glossary: 使用定义列表解释术语的后置章节。
bibliography: 放置参考资料的后置章节。
index: 放置索引目录种子或索引说明的后置章节；自动索引目录依赖转换器支持。

参考资料

每条参考资料可使用 bibliography anchor 作为稳定引用目标。

[asciidoctor-section-styles] Asciidoctor Docs, Section Styles for Articles and Books, https://docs.asciidoctor.org/asciidoc/latest/sections/styles/
[asciidoctor-parts] Asciidoctor Docs, Book Parts, https://docs.asciidoctor.org/asciidoc/latest/sections/parts/

索引

索引 section 位于书籍后置区域。正文中的索引词宏是索引词来源。

AsciiDoc 区分正文可见索引词和正文隐藏索引词：

写法含义

写法	含义
`<primary>`	正文可见，同时作为一级索引项。
	正文不可见，作为一级索引项。
	正文不可见，作为二级索引项。
	正文不可见，作为三级索引项。

<primary>

正文可见，同时作为一级索引项。

正文不可见，作为一级索引项。

正文不可见，作为二级索引项。

正文不可见，作为三级索引项。

正文中已经出现该词时，优先使用正文可见索引词。正文没有出现该词，但当前位置需要进入索引时，才使用正文隐藏索引词。

隐藏索引词应贴近它标记的段落内容。本书把隐藏索引词放在相关句子末尾，避免形成独立空段落。

Asciidoctor 的内置 HTML5 转换器不会自动生成索引目录。[index] section 是 PDF 和 DocBook 工具链自动填充索引目录的种子位置；在本 HTML 样本中，它展示后置索引章节的位置和索引词写法。

本书正文中的索引词示例：

indexterm2:[section]
indexterm:[section, hierarchy]
indexterm:[heading, discrete]

完整书籍结构标本