AsciiDoc 长文档、构建与多格式出版手册
AsciiDoc 面向长手册、交叉引用、条件内容和多格式出版。它仍是纯文本，但表达能力比常见 Markdown 方言更集中。官方文档明确区分写作格式与发布格式：处理器先把源文件解析成结构，再由转换器生成 HTML、DocBook、PDF 等输出。工程治理应围绕这条处理链展开，而不是把 .adoc 当成另一种后缀。
文档类型决定结构上限
安装 Asciidoctor 之前，先确定内容是 article、book 还是 manpage。默认 article 适合单篇技术说明，book 支持部、章和更复杂的前后置内容，manpage 有专门的头部约定。错误 doctype 可能不会立即报错，却会让目录、章节层级和多输出行为逐渐分叉。
仓库还需要固定属性命名、交叉引用 ID、include 根目录、图片目录和告警策略。属性能减少重复，但也会让同一源文件在不同参数下产生不同内容，因此构建命令必须完整记录传入值。
= 缓存服务运行手册
:doctype: book
:imagesdir: images
:sectanchors:
:source-highlighter: highlight.js
include::chapters/overview.adoc[leveloffset=+1]
include::chapters/recovery.adoc[leveloffset=+1]把处理器和转换器锁进项目
本机全局 gem 适合试用，不适合作为团队基线。Ruby 项目用 Bundler 固定 Asciidoctor 与扩展，容器项目固定基础镜像和字体；PDF 输出还要固定专用转换器、主题和字体文件。构建环境变化会改变分页、字形与代码块布局，即使源文件完全相同。
source "https://rubygems.org"
gem "asciidoctor", "<锁定版本>"
gem "asciidoctor-pdf", "<锁定版本>"配置影响通过小型出版夹具验证。夹具应包含中文标题、交叉引用、表格、代码块、图片、脚注和分页敏感内容。HTML 与 PDF 都要生成；前者检查结构和链接，后者检查字体、页眉页脚、分页和打印可读性。
正向验证与失败证据
正向实验从干净检出开始，执行依赖安装、HTML 构建、PDF 构建和链接检查。预期输出不仅是文件存在，还包括无严重告警、交叉引用可达、图片完整和中文字体正确。项目接入 CI 时，把 warning 级别和失败阈值写进命令，避免处理器带着重要告警返回成功。
反例需要故意引用不存在的 include、重复 ID、越界图片和未定义属性。错误应在构建阶段明确出现，并保留文件、行号和 include 栈。另一个常见故障是本机能读取仓库外文件，CI 无法读取；这正好证明 include 根目录没有被约束。
排障先看源解析，再看转换器和输出渲染。HTML 正常而 PDF 失败，多半落在 PDF 转换器、主题或字体；交叉引用只在组合文档失败，通常与 ID 或 include 层级有关。保留构建参数、运行时版本和最小失败章节，才能避免把同一错误在整本手册里重复定位。
include 与扩展的权限边界
include 会扩大处理器可读范围，扩展则可能执行 Ruby 代码或调用外部工具。构建服务应限制工作目录、文件访问和网络，远程 include 默认关闭。受信任仓库也不能直接读取主机凭证目录；容器挂载只暴露文档源、主题、字体和临时输出。
敏感数据不仅存在于正文。属性文件、构建日志、图片元数据和生成的 PDF 书签都可能泄露内部信息。示例要使用虚构域名和占位凭证，公开构建前扫描源与输出。权限上，作者修改正文，平台 owner 管理扩展与转换器，发布身份只访问交付目标。
多格式输出不是一次转换
HTML、PDF 和 DocBook 面向不同消费方式。共享语义应留在源文件，输出特有行为放在清晰的条件块或主题中。条件内容过多会把一本手册变成多个隐式产品，因此要记录每个输出的受众、必须章节和验证方法。
容量与成本主要来自图片、字体、PDF 渲染时间和全量 include 图。大型仓库可以按书籍或模块建立构建单元，但最终发布仍要做完整交叉引用验证。缓存只加速稳定输入；主题或处理器变化时应主动失效，不能用旧 PDF 掩盖新构建错误。
清理、回滚与迁移
清理章节时先查询交叉引用和 include 关系，再删除源文件。移除扩展前用夹具证明标准语法或替代扩展能生成等价结构。升级导致分页或 ID 大幅改变时，回滚锁文件、主题和字体，并把差异归类为内容变化或渲染变化。
迁移到 Markdown 或另一出版链时，先保护章节层级、交叉引用、警告块、表格和代码语义，再处理属性与条件内容。无法等价转换的出版能力应保留原始 .adoc 与生成物，并记录退出决策。恢复演练要求新环境能从源文件重建至少一种结构化输出和一种可交付输出。
AsciiDoc 的团队治理重点不是要求所有人掌握全部语法，而是让复杂能力集中在少量可解释的合同里。owner 维护处理器、扩展和主题，作者在稳定规则下写作，审查者能从 diff 看到事实变化。这样长文档才不会因为工具链只存在于个人电脑而失去可维护性。