API 选项

名称描述默认值允许值

名称	描述	默认值	允许值
`:attributes`	设置文档属性，除非是软设置，否则会覆盖文档中同名属性。属性值不会应用任何替换。在 Hash 格式中，键名必须是字符串，不能是符号（例如，`name: 'value'` 是无效的）。在此格式中，`nil` 值会硬性取消属性设置，`false` 值会软性取消属性设置。在字符串格式中，条目之间用空格分隔。要在值中包含空格，请在其前面加上反斜杠。	未设置	文档属性，以下格式 Hash `{ 'name' => 'value' }` Array `[ 'name=value' ]` String `'name=value'`
`:backend`	选择要使用的转换器。	`html5`	`html5`, `docbook5`, `manpage`, 或映射到可用转换器的后端
`:base_dir`	设置包含文档和资源的基目录（也称为工作目录）。	源文件的目录，如果源是从流中读取的，则为工作目录。	文件路径
`:catalog_assets`	如果设置为 `true`，解析器会捕获参考表中的图像和链接。（通常只包含 ID、脚注和索引项）。参考表可通过 `document` AST 对象上的 `references` 属性访问。（实验性功能）。	`false`	Boolean
`:converter`	指定一个用户提供的转换器类或实例，用于替换从 `backend` 值自动解析的转换器。	未设置	`Asciidoctor::Converter` 类或实例
`:doctype`	设置文档类型。	`article`	`article`, `book`, `manpage`, `inline`
`:eruby`	指定用于执行 ERB 编写的转换器模板的 eRuby 实现。	`erb`	`erb`, `erubis`
`:extensions`	一个 Ruby 块，用于为该处理器的实例注册（并可能定义）Asciidoctor 扩展。	未设置	符合 Asciidoctor 扩展 API 的 Ruby 块（与传递给 `Extensions.register` 方法的代码相同）。
`:extension_registry`	覆盖扩展注册表实例。此选项不提供包含要注册的扩展的 Ruby 块，而是允许您替换扩展注册表本身，从而完全控制如何为此处理器注册扩展。	未设置	`Extensions::Registry` 实例
`:logger`	全局 `LoggerManager.logger` 的快捷方式，用于为其分配新值。这是一个持久性更改，因此您必须在之后重置该值，或者每次调用 API 时都传递该选项。如果值为假，则分配一个空记录器，从而关闭日志记录。	未设置	`Logger` 实例
`:parse_header_only`	如果设置为 `true`，解析器将在读取完头部后停止。	`false`	Boolean
`:standalone`	如果设置为 `true`，则生成独立的输出文档（包括正文内容的 Shell，例如头部和尾部）。在转换为文件时，默认值为 `true`。否则，默认值为 `false`。此选项的已弃用别名是 `:header_footer`。此选项的默认值与 CLI 的默认值相反。	Varies	Boolean
`:mkdirs`	如果设置为 `true`，处理器将在输出目录尚不存在时创建必要的输出目录。	`false`	Boolean
`:parse`	如果设置为 `true`，则在将源传递给 `load` 或 `load_file` API 后立即（即，立即）解析源。如果设置为 `false`，则解析将推迟到显式调用 `parse` 方法为止。	`true`	Boolean
`:safe`	设置安全模式。	`:secure`	`:unsafe`, `:safe`, `:server`, `:secure`
`:sourcemap`	跟踪每个解析块的文件和行号。对于工具应用程序（其中转换后的输出与源文件之间的关联很重要）非常有用。	`false`	Boolean
`:template_cache`	启用模板转换器在读取模板文件源时使用的内置缓存。仅在指定了 `:template_dirs` 时才相关。	`true`	Boolean
`:template_dirs`	包含 Tilt 兼容的转换器模板的目录数组，将用于替代默认内置模板。	未设置	文件路径数组
`:template_engine`	用于自定义转换器模板的模板引擎。与引擎同名的 gem 将自动加载。此名称也用于构建自定义转换器模板的完整路径。	auto (根据找到的自定义转换器模板的文件扩展名设置)。	模板引擎名称（例如 `slim`、`haml`、`erb` 等）
`:template_engine_options`	直接传递给模板引擎的低级选项。	未设置	嵌套的选项 Hash，以模板引擎名称作为顶层键，选项名称作为第二层键。
`:timings`	捕获读取、解析和转换文档所需的时间。仅供内部使用。	未设置	`Asciidoctor::Timings` 实例
`:to_file`	要写入的输出文件名，或者 `true` 以使用默认输出文件名（`docname` + `outfilesuffix`）。	未设置	`true`, 文件路径
`:to_dir`	输出文件（或文件）的目标目录，相对于 `base_dir`。	包含源文件的目录，如果源是从流中读取的，则为工作目录。	文件路径

:attributes

设置文档属性，除非是软设置，否则会覆盖文档中同名属性。属性值不会应用任何替换。在 Hash 格式中，键名必须是字符串，不能是符号（例如，name: 'value' 是无效的）。在此格式中，nil 值会硬性取消属性设置，false 值会软性取消属性设置。在字符串格式中，条目之间用空格分隔。要在值中包含空格，请在其前面加上反斜杠。

未设置

文档属性，以下格式

Hash
{ 'name' => 'value' }

Array
[ 'name=value' ]

String
'name=value'

:backend

选择要使用的转换器。

html5

html5, docbook5, manpage, 或映射到可用转换器的后端

:base_dir

设置包含文档和资源的基目录（也称为工作目录）。

源文件的目录，如果源是从流中读取的，则为工作目录。

文件路径

:catalog_assets

如果设置为 true，解析器会捕获参考表中的图像和链接。（通常只包含 ID、脚注和索引项）。参考表可通过 document AST 对象上的 references 属性访问。（实验性功能）。

false

Boolean

:converter

指定一个用户提供的转换器类或实例，用于替换从 backend 值自动解析的转换器。

未设置

Asciidoctor::Converter 类或实例

:doctype

设置文档类型。

article

article, book, manpage, inline

:eruby

指定用于执行 ERB 编写的转换器模板的 eRuby 实现。

erb

erb, erubis

:extensions

一个 Ruby 块，用于为该处理器的实例注册（并可能定义）Asciidoctor 扩展。

未设置

符合 Asciidoctor 扩展 API 的 Ruby 块（与传递给 Extensions.register 方法的代码相同）。

:extension_registry

覆盖扩展注册表实例。此选项不提供包含要注册的扩展的 Ruby 块，而是允许您替换扩展注册表本身，从而完全控制如何为此处理器注册扩展。

未设置

Extensions::Registry 实例

:logger

全局 LoggerManager.logger 的快捷方式，用于为其分配新值。这是一个持久性更改，因此您必须在之后重置该值，或者每次调用 API 时都传递该选项。如果值为假，则分配一个空记录器，从而关闭日志记录。

未设置

Logger 实例

:parse_header_only

如果设置为 true，解析器将在读取完头部后停止。

false

Boolean

:standalone

如果设置为 true，则生成独立的输出文档（包括正文内容的 Shell，例如头部和尾部）。在转换为文件时，默认值为 true。否则，默认值为 false。此选项的已弃用别名是 :header_footer。此选项的默认值与 CLI 的默认值相反。

Varies

Boolean

:mkdirs

如果设置为 true，处理器将在输出目录尚不存在时创建必要的输出目录。

false

Boolean

:parse

如果设置为 true，则在将源传递给 load 或 load_file API 后立即（即，立即）解析源。如果设置为 false，则解析将推迟到显式调用 parse 方法为止。

true

Boolean

:safe

设置安全模式。

:secure

:unsafe, :safe, :server, :secure

:sourcemap

跟踪每个解析块的文件和行号。对于工具应用程序（其中转换后的输出与源文件之间的关联很重要）非常有用。

false

Boolean

:template_cache

启用模板转换器在读取模板文件源时使用的内置缓存。仅在指定了 :template_dirs 时才相关。

true

Boolean

:template_dirs

包含 Tilt 兼容的转换器模板的目录数组，将用于替代默认内置模板。

未设置

文件路径数组

:template_engine

用于自定义转换器模板的模板引擎。与引擎同名的 gem 将自动加载。此名称也用于构建自定义转换器模板的完整路径。

auto
(根据找到的自定义转换器模板的文件扩展名设置)。

模板引擎名称（例如 slim、haml、erb 等）

:template_engine_options

直接传递给模板引擎的低级选项。

未设置

嵌套的选项 Hash，以模板引擎名称作为顶层键，选项名称作为第二层键。

:timings

捕获读取、解析和转换文档所需的时间。仅供内部使用。

未设置

Asciidoctor::Timings 实例

:to_file

要写入的输出文件名，或者 true 以使用默认输出文件名（docname + outfilesuffix）。

未设置

true, 文件路径

:to_dir

输出文件（或文件）的目标目录，相对于 base_dir。

包含源文件的目录，如果源是从流中读取的，则为工作目录。

文件路径