API 选项

名称描述默认值允许的值

名称	描述	默认值	允许的值
`:attributes`	设置文档属性，这些属性会覆盖文档中同名的属性，除非是软设置。这些属性的值不应用任何替换。在哈希格式中，`nil` 值会硬取消设置属性，`false` 值会软取消设置属性。	未设置	文档属性以下格式：哈希 `{ 'name' => 'value' }` 数组 `[ 'name=value' ]` 字符串 (空格分隔) `'name=value'`
`:backend`	选择要使用的转换器。	`html5`	`html5`, `docbook5`, `manpage` 或者映射到可用转换器的后端
`:base_dir`	设置包含文档和资源的基础（又名工作）目录。	源文件的目录，或者如果源自流，则为工作目录。	文件路径
`:catalog_assets`	如果为 `true`，解析器会在引用表中捕获图像和链接。（通常只包括ID，脚注和索引术语）。引用表可通过 `document` AST对象上的 `references` 属性获得。 (实验性的)	`false`	布尔型
`:converter`	指定用户提供的转换器类或实例，替代从`backend`值自动解析出的转换器。	未设置	`Asciidoctor::Converter`类或实例
`:doctype`	设置文档类型。	`article`	`article`, `book`, `manpage`, `inline`
`:eruby`	指定用于执行编写在ERB中的转换器模板的eRuby实现。	`erb`	`erb`, `erubis`
`:extensions`	一个注册（也可能定义）Asciidoctor扩展的Ruby块，用于这个处理器实例。	未设置	符合Asciidoctor扩展API的Ruby块（同样的代码将被传递给`Extensions.register`方法）。
`:extension_registry`	覆盖扩展注册表实例。代替提供一个包含要注册的扩展的Ruby块，这个选项让你替换扩展注册表本身，让你完全控制这个处理器注册扩展的方式。	未设置	`Extensions::Registry`实例
`:logger`	简写来设置全局`LoggerManager.logger`的新值。这是持久的变化，所以之后你要么重置这个值，要么每次调用API时都通过这个选项。如果值是假的，它会分配一个空日志器，有效地关闭日志记录。	未设置	`Logger`实例
`:parse_header_only`	如果为`true`，解析器会在读取完头部后停止。	`false`	布尔型
`:standalone`	如果为`true`，会生成一个独立的输出文档（包括围绕正文内容的外壳，比如头部和尾部）。当转换为文件时，默认值为`true`。否则，默认值为`false`。这个选项的已弃用别名为`:header_footer`。这个选项的默认值与CLI的默认值相反。	变化	布尔型
`:mkdirs`	如果为`true`，如果必要的输出目录尚不存在，处理器会创建它们。	`false`	布尔型
`:parse`	如果为`true`，源代码会被积极地解析（即，一旦源码被传递给`load`或`load_file` API）。如果为`false`，解析会被推迟，直到明确调用`parse`方法。	`true`	布尔型
`:safe`	设置安全模式。	`:secure`	`:unsafe`, `:safe`, `:server`, `:secure`
`:sourcemap`	追踪每个已解析块的文件和行号。在关联转换输出和源文件非常重要的工具应用中非常有用。	`false`	布尔型
`:template_cache`	启用模板转换器在读取模板文件源码时使用的内置缓存。只有当`:template_dirs`被指定时才相关。	`true`	布尔型
`:template_dirs`	包含与Tilt兼容的转换器模板的目录数组，用来代替默认内置的模板。	未设置	文件路径数组
`:template_engine`	用于自定义转换器模板的模板引擎。与引擎同名的gem将会自动加载。这个名称也用于构建到自定义转换器模板的完整路径。	自动 (根据找到的自定义转换器模板的文件扩展名来设置)。	模板引擎名称（例如，`slim`、`haml`、`erb`等）
`:template_engine_options`	直接传递给模板引擎的低级选项。	not set	Nested Hash of options with the template engine name as the top-level key and the option name as the second-level key.
`:timings`	Capture time taken to read, parse, and convert document. Internal use only.	not set	`Asciidoctor::Timings` instance
`:to_file`	Name of the output file to write, or `true` to use the default output file (`docname` `outfilesuffix`).	not set	`true`, file path
`:to_dir`	Destination directory for output file(s), relative to `base_dir`.	Directory containing source file, or working directory if source is read from a stream.	File path

:attributes

设置文档属性，这些属性会覆盖文档中同名的属性，除非是软设置。这些属性的值不应用任何替换。在哈希格式中，nil 值会硬取消设置属性，false 值会软取消设置属性。

未设置

文档属性以下格式：

哈希
{ 'name' => 'value' }

数组
[ 'name=value' ]

字符串 (空格分隔)
'name=value'

:backend

选择要使用的转换器。

html5

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

:base_dir

设置包含文档和资源的基础（又名工作）目录。

源文件的目录，或者如果源自流，则为工作目录。

文件路径

:catalog_assets

如果为 true，解析器会在引用表中捕获图像和链接。（通常只包括ID，脚注和索引术语）。引用表可通过 document AST对象上的 references 属性获得。 (实验性的)

false

布尔型

:converter

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

未设置

`Asciidoctor::Converter`类或实例

:doctype

设置文档类型。

article

article, book, manpage, inline

:eruby

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

erb

erb, erubis

:extensions

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

未设置

符合Asciidoctor扩展API的Ruby块（同样的代码将被传递给`Extensions.register`方法）。

:extension_registry

覆盖扩展注册表实例。代替提供一个包含要注册的扩展的Ruby块，这个选项让你替换扩展注册表本身，让你完全控制这个处理器注册扩展的方式。

未设置

`Extensions::Registry`实例

:logger

简写来设置全局`LoggerManager.logger`的新值。这是持久的变化，所以之后你要么重置这个值，要么每次调用API时都通过这个选项。如果值是假的，它会分配一个空日志器，有效地关闭日志记录。

未设置

`Logger`实例

:parse_header_only

如果为`true`，解析器会在读取完头部后停止。

false

布尔型

:standalone

如果为`true`，会生成一个独立的输出文档（包括围绕正文内容的外壳，比如头部和尾部）。当转换为文件时，默认值为`true`。否则，默认值为`false`。这个选项的已弃用别名为`:header_footer`。这个选项的默认值与CLI的默认值相反。

变化

布尔型

:mkdirs

如果为`true`，如果必要的输出目录尚不存在，处理器会创建它们。

false

布尔型

:parse

如果为`true`，源代码会被积极地解析（即，一旦源码被传递给`load`或`load_file` API）。如果为`false`，解析会被推迟，直到明确调用`parse`方法。

true

布尔型

:safe

设置安全模式。

:secure

:unsafe, :safe, :server, :secure

:sourcemap

追踪每个已解析块的文件和行号。在关联转换输出和源文件非常重要的工具应用中非常有用。

false

布尔型

:template_cache

启用模板转换器在读取模板文件源码时使用的内置缓存。只有当`:template_dirs`被指定时才相关。

true

布尔型

:template_dirs

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

未设置

文件路径数组

:template_engine

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

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

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

:template_engine_options

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

not set

Nested Hash of options with the template engine name as the top-level key and the option name as the second-level key.

:timings

Capture time taken to read, parse, and convert document. Internal use only.

not set

Asciidoctor::Timings instance

:to_file

Name of the output file to write, or true to use the default output file (docname
outfilesuffix).

not set

true, file path

:to_dir

Destination directory for output file(s), relative to base_dir.

Directory containing source file, or working directory if source is read from a stream.

File path