转换选项

本文档描述了在转换文档时可以使用的选项列表。

名称描述默认值允许值

名称	描述	默认值	允许值
attributes	设置额外的文档属性，这些属性会覆盖文档中定义的同名属性，除非值以 `@` 结尾。	未设置	可以使用以下格式的任意数量的内置或用户定义的属性： JSON 格式： {'name': 'value'} 数组格式： ['name=value'] 字符串格式： 'name=value'
backend	选择要使用的转换器（作为已注册的关键字）。	html5	html5、docbook5，或通过活动转换器注册的任何后端
base_dir	设置包含文档和资源的基本目录（也称为工作目录）。	源文件的目录，或者如果源是从流中读取，则为工作目录。	文件路径
catalog_assets	如果为 `true`，则告诉解析器在参考表中捕获图片和链接。（通常只包含 ID、脚注和索引项）。参考表可以通过文档 AST 对象上的 `references` 属性访问。（实验性功能）。	false	boolean
doctype	设置文档类型。	article	article, book, manpage or inline
extensions_registry	覆盖扩展注册表实例。与提供包含要注册的扩展的 JavaScript 函数不同，此选项允许您替换扩展注册表本身，从而完全控制如何为该处理器注册扩展。	未设置	Extensions.Registry 实例
mkdirs	如果为 `true`，处理器将在输出目录尚不存在时创建必要的输出目录。	false	boolean
parse	如果为 `true`，则源文件会被立即解析（即，一旦源文件传递给 `load` 或 `loadFile` API）。如果为 `false`，则解析会被延迟，直到显式调用 `parse` 方法。	true	boolean
safe	设置安全模式	secure	unsafe, safe, server or secure
sourcemap	跟踪每个解析块的文件和行号。（对于工具应用程序非常有用，其中转换后的输出与源文件之间的关联很重要）。	false	boolean
standalone	如果为 `true`，则在输出中为正文内容添加文档头部和尾部（即框架）。	false	boolean
template_dirs	一个包含模板的目录数组，用于替代默认的内置模板。	未设置	文件路径数组
to_dir	输出文件的目标目录，相对于 `base_dir`。	包含源文件的目录，或者如果源是从流中读取，则为工作目录。	文件路径
to_file	要写入的输出文件的名称，或者如果为 `true`，则使用默认输出文件（`docname` + `outfilesuffix`）。	未设置	true, 文件路径

attributes

设置额外的文档属性，这些属性会覆盖文档中定义的同名属性，除非值以 @ 结尾。

未设置

可以使用以下格式的任意数量的内置或用户定义的属性：

JSON 格式： {'name': 'value'}

数组格式： ['name=value']

字符串格式： 'name=value'

backend

选择要使用的转换器（作为已注册的关键字）。

html5

html5、docbook5，或通过活动转换器注册的任何后端

base_dir

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

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

文件路径

catalog_assets

如果为 true，则告诉解析器在参考表中捕获图片和链接。（通常只包含 ID、脚注和索引项）。参考表可以通过文档 AST 对象上的 references 属性访问。（实验性功能）。

false

boolean

doctype

设置文档类型。

article

article, book, manpage or inline

extensions_registry

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

未设置

Extensions.Registry 实例

mkdirs

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

false

boolean

parse

如果为 true，则源文件会被立即解析（即，一旦源文件传递给 load 或 loadFile API）。如果为 false，则解析会被延迟，直到显式调用 parse 方法。

true

boolean

safe

设置安全模式

secure

unsafe, safe, server or secure

sourcemap

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

false

boolean

standalone

如果为 true，则在输出中为正文内容添加文档头部和尾部（即框架）。

false

boolean

template_dirs

一个包含模板的目录数组，用于替代默认的内置模板。

未设置

文件路径数组

to_dir

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

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

文件路径

to_file

要写入的输出文件的名称，或者如果为 true，则使用默认输出文件（docname + outfilesuffix）。

未设置

true, 文件路径

使用

在以下示例中，我们将 safe 选项定义为 unsafe，并且还定义了两个属性：

showtitle：显示嵌入文档的标题
icons：使用字体图标代替文本来表示警告

var content = '= Document title'
var html = asciidoctor.convert(content, { 'safe': 'server', 'attributes': { 'showtitle': true, 'icons': 'font' } })
console.log(html)
// <h1>Document title</h1>

您可以在 asciidoctor.org/docs/user-manual/#attribute-catalog 上阅读更多关于文档属性的内容。