Asciidoctor 命令行工具详解：从基础到高级用法

Asciidoctor 命令行工具详解：从基础到高级用法

asciidoctor :gem: A fast, open source text processor and publishing toolchain, written in Ruby, for converting AsciiDoc content to HTML 5, DocBook 5, and other formats. 项目地址: https://gitcode.com/gh_mirrors/as/asciidoctor

什么是 Asciidoctor？

Asciidoctor 是一个功能强大的文本处理器，用于将 AsciiDoc 格式的文档转换为 HTML、DocBook 等多种格式。它基于 Ruby 实现，相比传统的 AsciiDoc.py 提供了更快的处理速度和更丰富的功能特性。

基本使用

命令格式

最基本的 Asciidoctor 命令格式如下：

asciidoctor [选项]... 文件...

如果文件参数为 -，则表示从标准输入读取 AsciiDoc 源文件。

简单示例

将 AsciiDoc 文件转换为 HTML5：

asciidoctor document.adoc

这会生成一个名为 document.html 的输出文件。

核心选项详解

安全设置

1. 基础目录设置 (-B, --base-dir)

   • 指定包含文档和资源的基础目录
   • 默认情况下，基础目录是源文件所在目录或工作目录（当从流中读取时）
   • 与安全模式结合使用时，可用于限制程序执行环境

2. 安全模式 (-S, --safe-mode)

   • 设置安全级别：unsafe、safe、server 或 secure
   • 禁用源文件中潜在危险的宏，如 include::[]
   • 默认级别为 unsafe

文档属性设置

1. 自定义属性 (-a, --attribute)

   • 定义、覆盖或取消设置文档属性
   • 格式可以是：
     • NAME=VALUE（键值对）
     • NAME（值为空字符串）
     • NAME!（取消设置属性）
     • NAME=VALUE@（不覆盖源文档中已定义的属性）
   • 包含空格的属性值需要用引号括起来

2. 输出格式 (-b, --backend)

   • 指定输出格式：html5、docbook5、manpage 等
   • 支持别名：html（对应 html5）和 docbook（对应 docbook5）
   • 默认值为 html5

3. 文档类型 (-d, --doctype)

   • 设置文档类型：article、book、manpage 或 inline
   • 影响根元素（DocBook）或 HTML body 元素的样式类
   • 默认值为 article

文档转换控制

1. 输出目录 (-D, --destination-dir)

   • 指定输出文件的目标目录
   • 默认情况下，输出到源文件所在目录或工作目录

2. 模板引擎 (-E, --template-engine)

   • 指定用于自定义转换器模板的模板引擎
   • 自动加载与引擎同名的 gem

3. 嵌入式文档 (-e, --embedded 或 -s, --no-header-footer)

   • 生成嵌入式文档，不包含页眉、页脚和文档主体之外的内容
   • 适用于需要插入外部模板的文档

4. 输出文件 (-o, --out-file)

   • 指定输出文件名
   • 默认基于输入文件名加上后端扩展名
   • 使用 - 表示输出到标准输出

处理信息

1. 日志级别 (--log-level)

   • 设置应用程序日志消息的最低严重级别（默认：WARN）

2. 失败级别 (--failure-level)

   • 设置导致非零退出代码（即失败）的最低日志级别（默认：FATAL）

3. 调试选项 (-v, --verbose)

   • 将日志级别设置为 DEBUG，打印所有应用程序日志消息

4. 计时信息 (-t, --timings)

   • 向标准错误输出计时报告（读取、解析和转换时间）

高级特性

自定义模板

使用 -T, --template-dir 选项可以指定包含自定义转换器模板的目录：

asciidoctor -T custom_templates document.adoc

模板目录结构可以包含引擎名称和/或后端名称的子文件夹，以实现更精细的控制。

源映射

--sourcemap 选项使解析器为每个解析的块添加源位置信息，这对于需要访问源文档中块的文件和行号的扩展非常有用。

环境变量

Asciidoctor 支持 SOURCE_DATE_EPOCH 环境变量，用于指定所有输入文档的纪元时间和本地日期时间，有助于实现可重现的构建。

实用技巧

1. 批量转换：可以一次指定多个输入文件进行批量转换
2. 标准输入输出：使用 - 作为输入/输出文件参数来处理流数据
3. 属性优先级：命令行设置的属性会覆盖源文件中定义的属性（除非使用 @ 后缀）
4. 调试技巧：结合 -v 和 --trace 选项可以获取详细的调试信息

常见问题

1. 安全限制：在服务器环境下运行时，建议使用 server 或 secure 安全模式
2. 路径问题：使用 -B 和 -D 选项可以更好地控制文件和资源的路径解析
3. 模板覆盖：多个模板目录中的同名模板，后指定的会覆盖先指定的

总结

Asciidoctor 命令行工具提供了丰富的选项来控制文档转换过程，从基本的安全设置到高级的模板定制功能。掌握这些选项可以帮助您更高效地处理 AsciiDoc 文档，满足各种复杂的发布需求。

对于更复杂的场景，还可以结合 Ruby API 或扩展机制来实现更高级的功能。

asciidoctor :gem: A fast, open source text processor and publishing toolchain, written in Ruby, for converting AsciiDoc content to HTML 5, DocBook 5, and other formats. 项目地址: https://gitcode.com/gh_mirrors/as/asciidoctor