文档属性参考

文档属性用于配置处理器中的行为或传达有关文档及其环境的信息。这个页面列出了AsciiDoc中所有内建的（即保留的）文档属性。

除非另有标记，这些属性可以通过API使用`:attributes`选项进行修改（设置或取消），通过CLI使用`-a`选项修改，或者在文档中（通常在文档头部）使用属性条目来修改。

使用下面的图例来理解本页表格中的列和值。

默认设置	属性会被AsciiDoc处理器自动设置并赋予一个默认值。默认值会用粗体（例如，`skip`）表示。
允许的值	属性允许的值。数值和显示为_斜体_的值为指导性内容，表示值的类型（例如，任意、空、数字、1–5等）。 any — 任何值都被接受。 empty — 表示该属性不需要一个明确的值。仅通过设置属性即可启用它。 empty[=`effective`] — 在某些情况下，处理器会将空值解释为允许的非空值之一。这个有效值会以等号为前缀并用方括号括起来（例如，[=`auto`]）。属性引用将解析为空值而不是有效值。内置属性如果没有设置，可能会有一个暗示的值。暗示的值用括号括起来（例如，(`attributes`)）。使用属性引用无法解析暗示的值。如果属性不接受 any 或 empty，那么你必须只分配允许的值之一或指定的值类型。
仅头文件	属性必须在文档头部结束之前设置或取消设置（即通过API、CLI或在文档头部中设置）。否则，属性的赋值将不会对文档产生任何影响。如果一个属性没有被标记为_仅头部_，那么它可以在文档的任何地方设置，前提是该属性没有被API或CLI锁定。然而，更改属性只会影响随后的内容行为（按照文档顺序）。

内在属性

内在属性是由处理器自动设置的。这些属性提供有关正在处理的文档的信息（例如，docfile）、处理器运行的安全模式信息（例如，safe-mode-name）以及有关用户环境的信息（例如，user-home）。

许多这些属性是只读的，这意味着它们不能被修改（有一些例外）。那些不是只读的属性被标记为可修改的。被同时标记为可修改和仅限API/CLI的属性只能通过API或CLI设置。所有其他被标记为可修改的属性必须在标题结束之前设置（即，仅限标题）。

名称允许的值是否可修改仅限API/CLI 备注

名称	允许的值	是否可修改	仅限API/CLI	备注
`backend`	any ex. html5	Yes	No	The backend used to select and activate the converter that creates the output file. Usually named according to the output format (e.g., `html5`)
`backend-<backend>`	empty	No	n/a	A convenience attribute for checking which backend is selected. <backend> is the value of the `backend` attribute (e.g., `backend-html5`). Only one such attribute is set at time.
`basebackend`	任意例如 html	No	n/a	后端的通用基础。通常从后端值中去掉尾随数字得到（例如，docbook5`的basebackend是`docbook）。也可能指转换器使用的内部后端（例如，pdf`的basebackend是`html）。
`basebackend-<basebackend>`	空	No	n/a	检查哪个basebackend处于活动状态的便捷属性。<basebackend>是`basebackend`属性的值（例如，`basebackend-html`）。一次只设置一个此类属性。
`docdate`	date (ISO) ex. 2019-01-04	Yes	No	Last modified date of the source document.^[1,2]
`docdatetime`	datetime (ISO) ex. 2019-01-04 19:26:06 UTC	Yes	No	Last modified date and time of the source document.^[1,2]
`docdir`	directory path ex. /home/user/docs	If input is a string	Yes	Full path of the directory that contains the source document. Empty if the safe mode is SERVER or SECURE (to conceal the file’s location).
`docfile`	file path ex. /home/user/docs/userguide.adoc	If input is a string	Yes	Full path of the source document. Truncated to the basename if the safe mode is SERVER or SECURE (to conceal the file’s location).
`docfilesuffix`	file extension ex. .adoc	If input is a string	Yes	File extension of the source document, including the leading period.
`docname`	file stem basename ex. userguide	If input is a string	Yes	Root name of the source document (no leading path or file extension).
`doctime`	time (ISO) ex. 19:26:06 UTC	Yes	No	Last modified time of the source document.^[1,2]
`doctype-<doctype>`	empty	No	n/a	A convenience attribute for checking the doctype of the document. <doctype> is the value of the `doctype` attribute (e.g., `doctype-book`). Only one such attribute is set at time.
`docyear`	integer ex. 2024	Yes	No	Year that the document was last modified.^[1,2]
`embedded`	empty	No	n/a	Only set if content is being converted to an embedded document (i.e., body of document only).
`filetype`	any ex. html	If input is a string	Yes	File extension of the output file name (without leading period).
`filetype-<filetype>`	empty	No	n/a	A convenience attribute for checking the filetype of the output. <filetype> is the value of the `filetype` attribute (e.g., `filetype-html`). Only one such attribute is set at time.
`htmlsyntax`	`html` `xml`	No	n/a	Syntax used when generating the HTML output. Controlled by and derived from the backend name (html=html or xhtml=html).
`localdate`	date (ISO) ex. 2019-02-17	Yes	No	Date when the document was converted.^[2]
`localdatetime`	datetime (ISO) ex. 2019-02-17 19:31:05 UTC	Yes	No	Date and time when the document was converted.^[2]
`localtime`	time (ISO) ex. 19:31:05 UTC	Yes	No	Time when the document was converted.^[2]
`localyear`	integer ex. 2024	Yes	No	Year when the document was converted.^[2]
`outdir`	directory path ex. /home/user/docs/dist	No	n/a	Full path of the output directory. (Cannot be referenced in the content. Only available to the API once the document is converted).
`outfile`	file path ex. /home/user/docs/dist/userguide.html	No	n/a	Full path of the output file. (Cannot be referenced in the content. Only available to the API once the document is converted).
`outfilesuffix`	file extension ex. .html	Yes	No	File extension of the output file (starting with a period) as determined by the backend (`.html` for `html`, `.xml` for `docbook`, etc.).
`safe-mode-level`	`0` `1` `10` `20`	No	n/a	Numeric value of the safe mode setting. (0=UNSAFE, 1=SAFE, 10=SERVER, 20=SECURE).
`safe-mode-name`	`UNSAFE` `SAFE` `SERVER` `SECURE`	No	n/a	Textual value of the safe mode setting.
`safe-mode-unsafe`	empty	No	n/a	Set if the safe mode is UNSAFE.
`safe-mode-safe`	empty	No	n/a	Set if the safe mode is SAFE.
`safe-mode-server`	empty	No	n/a	Set if the safe mode is SERVER.
`safe-mode-secure`	empty	No	n/a	Set if the safe mode is SECURE.
`user-home`	directory path ex. /home/user	No	n/a	Full path of the home directory for the current user. Masked as `.` if the safe mode is SERVER or SECURE.

backend

any
ex. html5

Yes

The backend used to select and activate the converter that creates the output file. Usually named according to the output format (e.g., html5)

backend-<backend>

empty

n/a

A convenience attribute for checking which backend is selected. <backend> is the value of the backend attribute (e.g., backend-html5). Only one such attribute is set at time.

basebackend

任意
例如 html

n/a

后端的通用基础。通常从后端值中去掉尾随数字得到（例如，docbook5`的basebackend是`docbook）。也可能指转换器使用的内部后端（例如，pdf`的basebackend是`html）。

basebackend-<basebackend>

空

n/a

检查哪个basebackend处于活动状态的便捷属性。<basebackend>是`basebackend`属性的值（例如，basebackend-html）。一次只设置一个此类属性。

docdate

date (ISO)
ex. 2019-01-04

Yes

Last modified date of the source document.^[1,2]

docdatetime

datetime (ISO)
ex. 2019-01-04 19:26:06 UTC

Yes

Last modified date and time of the source document.^[1,2]

docdir

directory path
ex. /home/user/docs

If input is a string

Yes

Full path of the directory that contains the source document. Empty if the safe mode is SERVER or SECURE (to conceal the file’s location).

docfile

file path
ex. /home/user/docs/userguide.adoc

If input is a string

Yes

Full path of the source document. Truncated to the basename if the safe mode is SERVER or SECURE (to conceal the file’s location).

docfilesuffix

file extension
ex. .adoc

If input is a string

Yes

File extension of the source document, including the leading period.

docname

file stem basename
ex. userguide

If input is a string

Yes

Root name of the source document (no leading path or file extension).

doctime

time (ISO)
ex. 19:26:06 UTC

Yes

Last modified time of the source document.^[1,2]

doctype-<doctype>

empty

n/a

A convenience attribute for checking the doctype of the document. <doctype> is the value of the doctype attribute (e.g., doctype-book). Only one such attribute is set at time.

docyear

integer
ex. 2024

Yes

Year that the document was last modified.^[1,2]

embedded

empty

n/a

Only set if content is being converted to an embedded document (i.e., body of document only).

filetype

any
ex. html

If input is a string

Yes

File extension of the output file name (without leading period).

filetype-<filetype>

empty

n/a

A convenience attribute for checking the filetype of the output. <filetype> is the value of the filetype attribute (e.g., filetype-html). Only one such attribute is set at time.

htmlsyntax

html
xml

n/a

Syntax used when generating the HTML output. Controlled by and derived from the backend name (html=html or xhtml=html).

localdate

date (ISO)
ex. 2019-02-17

Yes

Date when the document was converted.^[2]

localdatetime

datetime (ISO)
ex. 2019-02-17 19:31:05 UTC

Yes

Date and time when the document was converted.^[2]

localtime

time (ISO)
ex. 19:31:05 UTC

Yes

Time when the document was converted.^[2]

localyear

integer
ex. 2024

Yes

Year when the document was converted.^[2]

outdir

directory path
ex. /home/user/docs/dist

n/a

Full path of the output directory. (Cannot be referenced in the content. Only available to the API once the document is converted).

outfile

file path
ex. /home/user/docs/dist/userguide.html

n/a

Full path of the output file. (Cannot be referenced in the content. Only available to the API once the document is converted).

outfilesuffix

file extension
ex. .html

Yes

File extension of the output file (starting with a period) as determined by the backend (.html for html, .xml for docbook, etc.).

safe-mode-level

0
1
10
20

n/a

Numeric value of the safe mode setting. (0=UNSAFE, 1=SAFE, 10=SERVER, 20=SECURE).

safe-mode-name

UNSAFE
SAFE
SERVER
SECURE

n/a

Textual value of the safe mode setting.

safe-mode-unsafe

empty

n/a

Set if the safe mode is UNSAFE.

safe-mode-safe

empty

n/a

Set if the safe mode is SAFE.

safe-mode-server

empty

n/a

Set if the safe mode is SERVER.

safe-mode-secure

empty

n/a

Set if the safe mode is SECURE.

user-home

directory path
ex. /home/user

n/a

Full path of the home directory for the current user. Masked as . if the safe mode is SERVER or SECURE.

'''^[1] 仅反映源文档文件的最后修改时间。它不考虑包含文件的最后修改时间。'''

如果设置了SOURCE_DATE_EPOCH环境变量，则该属性的值是根据与该环境变量中存储的时间戳（作为一个整数）对应的UTC日期对象构建的。这种方式提供了一种使转换可复现的方法。有关SOURCE_DATE_EPOCH环境变量的更多信息，请查看源日期纪元规范 https://reproducible-builds.org/specs/source-date-epoch/。否则，日期表示为本地时区时间，会报告为时区偏移量（例如，-0600）或UTC（如果时区偏移量为0）。要强制使用UTC，请在调用Asciidoctor时设置`TZ=UTC`环境变量。

合规属性

.名称允许的值默认设置仅限表头注释

.名称	允许的值	默认设置	仅限表头	注释
`attribute-missing`	`drop` `drop-line` `skip` `warn`	Yes	No	Controls how missing attribute references are handled.
`attribute-undefined`	`drop` `drop-line`	Yes	No	Controls how attribute unassignments are handled.
`compat-mode`	empty	No	No	Controls when the legacy parsing mode is used to parse the document.
`experimental`	empty	No	Yes	Enables macros:ui-macros.html and the macros:keyboard-macro.html.
`reproducible`	empty	No	Yes	Prevents last-updated date from being added to HTML footer or DocBook info element. Useful for storing the output in a source code control system as it prevents spurious changes every time you convert the document. Alternately, you can use the SOURCE_DATE_EPOCH environment variable, which sets the epoch of all source documents and the local datetime to a fixed value.
`skip-front-matter`	empty	No	Yes	Consume YAML-style frontmatter at top of document and store it in `front-matter` attribute.

attribute-missing

drop
drop-line
skip
warn

Yes

Controls how missing attribute references are handled.

attribute-undefined

drop
drop-line

Yes

Controls how attribute unassignments are handled.

compat-mode

empty

Controls when the legacy parsing mode is used to parse the document.

experimental

empty

Yes

Enables macros:ui-macros.html and the macros:keyboard-macro.html.

reproducible

empty

Yes

Prevents last-updated date from being added to HTML footer or DocBook info element. Useful for storing the output in a source code control system as it prevents spurious changes every time you convert the document. Alternately, you can use the SOURCE_DATE_EPOCH environment variable, which sets the epoch of all source documents and the local datetime to a fixed value.

skip-front-matter

empty

Yes

Consume YAML-style frontmatter at top of document and store it in front-matter attribute.

本地化和编号属性

.名称允许的值默认设置仅限表头注释

.名称	允许的值	默认设置	仅限表头	注释
`appendix-caption`	any `附录`	Yes	No	在附录标题前添加的标签。
`appendix-number`	character (`@`)	No	No	设置附录编号序列的初始值。^[1]
`appendix-refsig`	any `附录`	Yes	No	添加到附录标题交叉引用的标识符。
`caution-caption`	any `警告`	Yes	No	在未启用图标时用于标记CAUTION警告的文本。
`chapter-number`	number (`0`)	No	No	设置章节编号序列的初始值。^[1] 仅限书籍文档类型。
`chapter-refsig`	any `章节`	Yes	No	添加到章节标题交叉引用的标识符。仅限书籍文档类型。
`chapter-signifier`	any	No	No	添加到一级节标题（章节）的标签。仅限书籍文档类型。
`example-caption`	any `示例`	Yes	No	用于标记示例块的文本。
`example-number`	number (`0`)	No	No	设置示例编号序列的初始值。^[1]
`figure-caption`	any `图`	Yes	No	用于标记图像和插图的文本。
`figure-number`	number (`0`)	No	No	设置图像编号序列的初始值。^[1]
`footnote-number`	number (`0`)	No	No	设置脚注编号序列的初始值。^[1]
`important-caption`	any `重要`	Yes	No	在未启用图标时用于标记IMPORTANT警告的文本。
`lang`	BCP 47语言标签 (`en`)	No	Yes	指定在输出文档的文档元素上的语言标签。参考HTML规范的https://html.spec.whatwg.org/#the-lang-and-xml:lang-attributes[lang和xml:lang属性部分^]了解更多关于此属性的可接受值。
`last-update-label`	any `最后更新`	Yes	Yes	用于页脚“最后更新”标签的文本。
`listing-caption`	any	No	No	用于标记列表块的文本。
`listing-number`	number (`0`)	No	No	设置列表编号序列的初始值。^[1]
`manname-title`	any (`名称`)	No	Yes	man页面中程序名称部分的标签。
`nolang`	empty	No	Yes	阻止在输出文档的根元素上添加`lang`属性。
`note-caption`	any `注释`	Yes	No	在未启用图标时用于标记NOTE注释的文本。
`part-refsig`	any `部分`	Yes	No	添加到部分标题交叉引用的标识符。仅限书籍文档类型。
`part-signifier`	any	No	No	添加到零级节标题（部分）的标签。仅限书籍文档类型。
`preface-title`	any	No	No	当`doctype`是`book`时，匿名前言的标题文本。
`section-refsig`	any `章节`	Yes	No	在交叉引用文本中为编号节的标题添加的标识符。
`table-caption`	any `表`	Yes	No	表格标题前添加的文本标签。
`table-number`	number (`0`)	No	No	设置表格编号序列的初始值。^[1]
`tip-caption`	any `提示`	Yes	No	在未启用图标时用于标记TIP提醒的文本。
`toc-title`	any `目录`	Yes	Yes	目录的标题。
`untitled-label`	any `无标题`	Yes	Yes	如果文档没有文档标题，则使用默认文档标题。
`version-label`	any `版本`	Yes	Yes	参见document:version-label.html。
`warning-caption`	any `警告`	Yes	No	在未启用图标时用于标记WARNING警告的文本。

appendix-caption

any
附录

Yes

在附录标题前添加的标签。

appendix-number

character
(@)

设置附录编号序列的初始值。^[1]

appendix-refsig

any
附录

Yes

添加到附录标题交叉引用的标识符。

caution-caption

any
警告

Yes

在未启用图标时用于标记CAUTION警告的文本。

chapter-number

number
(0)

设置章节编号序列的初始值。^[1] 仅限书籍文档类型。

chapter-refsig

any
章节

Yes

添加到章节标题交叉引用的标识符。仅限书籍文档类型。

chapter-signifier

any

添加到一级节标题（章节）的标签。仅限书籍文档类型。

example-caption

any
示例

Yes

用于标记示例块的文本。

example-number

number
(0)

设置示例编号序列的初始值。^[1]

figure-caption

any
图

Yes

用于标记图像和插图的文本。

figure-number

number
(0)

设置图像编号序列的初始值。^[1]

footnote-number

number
(0)

设置脚注编号序列的初始值。^[1]

important-caption

any
重要

Yes

在未启用图标时用于标记IMPORTANT警告的文本。

lang

BCP 47语言标签
(en)

Yes

指定在输出文档的文档元素上的语言标签。参考HTML规范的https://html.spec.whatwg.org/#the-lang-and-xml:lang-attributes[lang和xml:lang属性部分^]了解更多关于此属性的可接受值。

last-update-label

any
最后更新

Yes

用于页脚“最后更新”标签的文本。

listing-caption

any

用于标记列表块的文本。

listing-number

number
(0)

设置列表编号序列的初始值。^[1]

manname-title

any
(名称)

Yes

man页面中程序名称部分的标签。

nolang

empty

Yes

阻止在输出文档的根元素上添加`lang`属性。

note-caption

any
注释

Yes

在未启用图标时用于标记NOTE注释的文本。

part-refsig

any
部分

Yes

添加到部分标题交叉引用的标识符。仅限书籍文档类型。

part-signifier

any

添加到零级节标题（部分）的标签。仅限书籍文档类型。

preface-title

any

当`doctype`是`book`时，匿名前言的标题文本。

section-refsig

any
章节

Yes

在交叉引用文本中为编号节的标题添加的标识符。

table-caption

any
表

Yes

表格标题前添加的文本标签。

table-number

number
(0)

设置表格编号序列的初始值。^[1]

tip-caption

any
提示

Yes

在未启用图标时用于标记TIP提醒的文本。

toc-title

any
目录

Yes

目录的标题。

untitled-label

any
无标题

Yes

如果文档没有文档标题，则使用默认文档标题。

version-label

any
版本

Yes

参见document:version-label.html。

warning-caption

any
警告

Yes

在未启用图标时用于标记WARNING警告的文本。

文档元数据属性

.名称允许的值默认设置仅限表头注释

.名称	允许的值	默认设置	仅限表头	注释
`app-name`	any	No	Yes	在HTML文档头部为移动设备添加`application-name`元数据元素。
`author`	any	从作者信息行提取	Yes	可以通过作者信息行自动设置，或者显示指定。参见document:author-information.html。
`authorinitials`	any	从`author`属性中提取	Yes	默认情况下根据作者属性派生。参见document:author-information.html。
`authors`	any	从作者信息行提取	Yes	可以通过作者信息行自动设置，或者作为逗号分隔的值列表显式设置。参见document:author-information.html。
`copyright`	any	No	Yes	在HTML文档头部添加`copyright`元数据元素。
`doctitle`	any	如果文档有标题，则为“Yes”	Yes	参见doctitle属性。
`description`	any	No	Yes	在HTML文档头部添加description元数据元素。
`email`	any	从作者信息行提取	Yes	可以是任何行内宏，比如一个URL。参见document:author-information.html。
`firstname`	any	从作者信息行提取	Yes	参见document:author-information.html。
`front-matter`	any	如果前言被捕获则为“Yes”	n/a	如果通过API或CLI设置了`skip-front-matter`，那么任何从文档顶部剥离的YAML风格前言都将存储在这个属性中。
`keywords`	any	No	Yes	在HTML文档头部添加keywords元数据元素。
`lastname`	any	从作者信息行提取	Yes	参见document:author-information.html。
`middlename`	any	从作者信息行提取	Yes	参见document:author-information.html。
`orgname`	any	No	Yes	将`<orgname>`元素值添加到DocBook信息元素中。
`revdate`	any	从修订信息行提取	Yes	参见document:revision-information.html。
`revremark`	any	从修订信息行提取	Yes	参见document:revision-information.html。
`revnumber`	any	从修订信息行提取	Yes	参见document:revision-information.html。
`title`	any	No	Yes	HTML <head>`中<title>`元素的值或输出文档主DocBook `<info>`中的值。未指定文档标题时使用作为备选。参见title属性。

app-name

any

Yes

在HTML文档头部为移动设备添加`application-name`元数据元素。

author

any

从作者信息行提取

Yes

可以通过作者信息行自动设置，或者显示指定。参见document:author-information.html。

authorinitials

any

从`author`属性中提取

Yes

默认情况下根据作者属性派生。参见document:author-information.html。

authors

any

从作者信息行提取

Yes

可以通过作者信息行自动设置，或者作为逗号分隔的值列表显式设置。参见document:author-information.html。

copyright

any

Yes

在HTML文档头部添加`copyright`元数据元素。

doctitle

any

如果文档有标题，则为“Yes”

Yes

参见doctitle属性。

description

any

Yes

在HTML文档头部添加description元数据元素。

email

any

从作者信息行提取

Yes

可以是任何行内宏，比如一个URL。参见document:author-information.html。

firstname

any

从作者信息行提取

Yes

参见document:author-information.html。

front-matter

any

如果前言被捕获则为“Yes”

n/a

如果通过API或CLI设置了`skip-front-matter`，那么任何从文档顶部剥离的YAML风格前言都将存储在这个属性中。

keywords

any

Yes

在HTML文档头部添加keywords元数据元素。

lastname

any

从作者信息行提取

Yes

参见document:author-information.html。

middlename

any

从作者信息行提取

Yes

参见document:author-information.html。

orgname

any

Yes

将`<orgname>`元素值添加到DocBook信息元素中。

revdate

any

从修订信息行提取

Yes

参见document:revision-information.html。

revremark

any

从修订信息行提取

Yes

参见document:revision-information.html。

revnumber

any

从修订信息行提取

Yes

参见document:revision-information.html。

title

any

Yes

HTML <head>`中<title>`元素的值或输出文档主DocBook `<info>`中的值。未指定文档标题时使用作为备选。参见title属性。

章节标题和目录属性

.名称允许的值默认设置仅限表头注释

.名称	允许的值	默认设置	仅限表头	注释
`idprefix`	valid XML ID start character `_`	Yes	No	Prefix of auto-generated section IDs. See Change the ID prefix.
`idseparator`	valid XML ID character `_`	Yes	No	Word separator used in auto-generated section IDs. See Change the ID word separator.
`leveloffset`	[+-]0–5	No	No	Increases or decreases level of headings below assignment. A leading + or - makes the value relative.
`partnums`	empty	No	No	Enables numbering of parts. See Number book parts. Book doctype only.
`sectanchors`	empty	No	No	Adds anchor in front of section title on mouse cursor hover.
`sectids`	*empty*	Yes	No	Generates and assigns an ID to any section that does not have an ID. See Disable automatic ID generation.
`sectlinks`	empty	No	No	Turns section titles into self-referencing links.
`sectnums`	empty `all`	No	No	Numbers sections to depth specified by `sectnumlevels`.
`sectnumlevels`	0–5 (`3`)	No	No	Controls depth of section numbering.
`title-separator`	any	No	Yes	Character used to separate document title and subtitle.
`toc`	empty[=`auto`] `auto` `left` `right` `macro` `preamble`	No	Yes	Turns on table of contents and specifies its location.
`toclevels`	1–5 (`2`)	No	Yes	Maximum section level to display.
`fragment`	empty	No	Yes	Informs parser that document is a fragment and that it shouldn’t enforce proper section nesting.

idprefix

valid XML ID start character
_

Yes

Prefix of auto-generated section IDs. See Change the ID prefix.

idseparator

valid XML ID character
_

Yes

Word separator used in auto-generated section IDs. See Change the ID word separator.

leveloffset

[+-]0–5

Increases or decreases level of headings below assignment. A leading + or - makes the value relative.

partnums

empty

Enables numbering of parts. See Number book parts. Book doctype only.

sectanchors

empty

Adds anchor in front of section title on mouse cursor hover.

sectids

empty

Yes

Generates and assigns an ID to any section that does not have an ID. See Disable automatic ID generation.

sectlinks

empty

Turns section titles into self-referencing links.

sectnums

empty
all

Numbers sections to depth specified by sectnumlevels.

sectnumlevels

0–5
(3)

Controls depth of section numbering.

title-separator

any

Yes

Character used to separate document title and subtitle.

toc

empty[=auto]
auto
left
right
macro
preamble

Yes

Turns on table of contents and specifies its location.

toclevels

1–5
(2)

Yes

Maximum section level to display.

fragment

empty

Yes

Informs parser that document is a fragment and that it shouldn’t enforce proper section nesting.

通用内容和格式属性

.名称允许的值默认设置仅限表头注释

.名称	允许的值	默认设置	仅限表头	注释
`asset-uri-scheme`	empty `http` (`https`)	No	Yes	控制托管在CDN上的资源所使用的协议。
`cache-uri`	empty	No	Yes	缓存从URI读取的内容。
`data-uri`	empty	No	Yes	在HTML元素中嵌入图形作为数据URI元素，以使文件完全独立。
`docinfo`	empty[=`private`] `shared` `private` `shared-head` `private-head` `shared-footer` `private-footer`	No	Yes	Read input from one or more DocBook info files.
`docinfodir`	directory path	No	Yes	文档信息文件的位置。如果未指定，默认为源文件所在的目录。
`docinfosubs`	comma-separated substitution names (`attributes`)	No	Yes	AsciiDoc替换，这些替换应用于docinfo内容。
`doctype`	`article` `book` `inline` `manpage`	Yes	Yes	Output document type.
`eqnums`	empty[=`AMS`] `AMS` `all` `none`	No	Yes	在HTML输出（MathJax）中控制LaTeX块的自动公式编号。如果值为AMS，则只有在`\begin{equation}...\end{equation}`容器中封闭的LaTeX内容会被编号。如果值为all，则所有LaTeX块都将被编号。见https://docs.mathjax.org/en/v2.5-latest/tex.html#automatic-equation-numbering[MathJax中的公式编号]。
`hardbreaks-option`	empty	No	No	参考:blocks:hard-line-breaks.adoc#per-document[保留硬换行]。
`hide-uri-scheme`	empty	No	No	参考:macros:links.adoc#hide-uri-scheme[隐藏原始链接的URI方案]。
`media`	`prepress` `print` (`screen`)	No	Yes	指定输出的媒体类型并启用特定于该媒体类型的行为。仅限PDF转换器。
`nofooter`	empty	No	Yes	关闭页脚。
`nofootnotes`	empty	No	Yes	关闭脚注。
`无标题头`	空白	No	Yes	关闭标题头。
`notitle`	无标题	empty 空值	No	Yes
`在嵌入文档中隐藏文档标题。与 showtitle 属性互斥。`	outfilesuffix	文件扩展名例如 .html	Yes	Yes
`输出文件的文件扩展名，包括点（.），例如 .html。`	pagewidth	integer (`425`)	No	Yes
`用来计算DocBook输出中表格绝对宽度的页面宽度。`	relfileprefix	empty path segment	No	No
`添加到相对xrefs的路径前缀。`	relfilesuffix	文件扩展名* 路径段* 例如 .html	Yes	No
添加到相对交叉引用的路径后缀（例如，文件扩展名）。默认为`outfilesuffix`属性的值。（优先于修改outfilesuffix）。	show-link-uri	empty	No	No
`在链接文本之后打印链接的URI。仅限PDF转换器。`	showtitle	empty	No	Yes
显示嵌入文档中的文档标题。和`notitle`属性互斥。	stem	`空`[=`asciimath`] `asciimath` `latexmath`	No	Yes
`启用数学处理和解释器。`	table-frame	(`全部`) `两端` `两侧` `无`	No	No
控制表格的`frame`属性的默认值。	table-grid	(`全部`) `列` `行` `无`	No	No
控制表格的`grid`属性的默认值。	table-stripes	(`无`) `偶数行` `奇数行` `悬停` `全部`	No	No
控制表格的`stripes`属性的默认值。	tabsize	整数 (≥ 0)	No	No
`在原样内容块中将标签转换为空格（例如，列表，字面量）。`	webfonts	空	Yes	Yes
控制在使用默认样式表时是否加载网络字体。设置为空时，使用来自Google字体的默认字体集。非空值替换Google字体URL中的`family`查询字符串参数。	xrefstyle	`完整` `简短` `基础`	No	No

asset-uri-scheme

empty
http
(https)

Yes

控制托管在CDN上的资源所使用的协议。

cache-uri

empty

Yes

缓存从URI读取的内容。

data-uri

empty

Yes

在HTML元素中嵌入图形作为数据URI元素，以使文件完全独立。

docinfo

empty[=private]
shared
private
shared-head
private-head
shared-footer
private-footer

Yes

Read input from one or more DocBook info files.

docinfodir

directory path

Yes

文档信息文件的位置。如果未指定，默认为源文件所在的目录。

docinfosubs

comma-separated substitution names
(attributes)

Yes

AsciiDoc替换，这些替换应用于docinfo内容。

doctype

article
book
inline
manpage

Yes

Output document type.

eqnums

empty[=AMS]
AMS
all
none

Yes

在HTML输出（MathJax）中控制LaTeX块的自动公式编号。如果值为AMS，则只有在`\begin{equation}...\end{equation}`容器中封闭的LaTeX内容会被编号。如果值为all，则所有LaTeX块都将被编号。见https://docs.mathjax.org/en/v2.5-latest/tex.html#automatic-equation-numbering[MathJax中的公式编号]。

hardbreaks-option

empty

参考:blocks:hard-line-breaks.adoc#per-document[保留硬换行]。

hide-uri-scheme

empty

参考:macros:links.adoc#hide-uri-scheme[隐藏原始链接的URI方案]。

media

prepress
print
(screen)

Yes

指定输出的媒体类型并启用特定于该媒体类型的行为。仅限PDF转换器。

nofooter

empty

Yes

关闭页脚。

nofootnotes

empty

Yes

关闭脚注。

无标题头

空白

Yes

关闭标题头。

notitle

无标题

empty 空值

Yes

在嵌入文档中隐藏文档标题。与 showtitle 属性互斥。

outfilesuffix

文件扩展名
例如 .html

Yes

输出文件的文件扩展名，包括点（.），例如 .html。

pagewidth

integer
(425)

Yes

用来计算DocBook输出中表格绝对宽度的页面宽度。

relfileprefix

empty
path segment

添加到相对xrefs的路径前缀。

relfilesuffix

文件扩展名*
路径段*
例如 .html

Yes

添加到相对交叉引用的路径后缀（例如，文件扩展名）。默认为`outfilesuffix`属性的值。（优先于修改outfilesuffix）。

show-link-uri

empty

在链接文本之后打印链接的URI。仅限PDF转换器。

showtitle

empty

Yes

显示嵌入文档中的文档标题。和`notitle`属性互斥。

stem

空[=asciimath]
asciimath
latexmath

Yes

启用数学处理和解释器。

table-frame

(全部)
两端
两侧
无

控制表格的`frame`属性的默认值。

table-grid

(全部)
列
行
无

控制表格的`grid`属性的默认值。

table-stripes

(无)
偶数行
奇数行
悬停
全部

控制表格的`stripes`属性的默认值。

tabsize

整数 (≥ 0)

在原样内容块中将标签转换为空格（例如，列表，字面量）。

webfonts

空

Yes

控制在使用默认样式表时是否加载网络字体。设置为空时，使用来自Google字体的默认字体集。非空值替换Google字体URL中的`family`查询字符串参数。

xrefstyle

完整
简短
基础

图像和图标属性

.名称允许的值默认设置仅限表头注释

.名称	允许的值	默认设置	仅限表头	注释
`参数名`	参数值	默认值	是否必填	说明
`+`	:---	:---	:---	:---
`:---`	+	iconfont-cdn	网址	+ (默认的CDN网址)
`No`	Yes	如果不特别指定，将使用cdnjs.com服务。用于覆盖链接至Font Awesome样式表的CDN。	iconfont-name	任意值
`+ (font-awesome)`	No	Yes	用于覆盖图标字体样式表的名称。	iconfont-remote
`empty`	Yes	Yes	允许使用CDN来解析图标字体。仅当`icons`属性的值为`font`时相关。	icons
`empty[=image] image font`	No	Yes	选择使用图像或字体图标替代文本进行警告。任何其他值被视为icontype，并将值设置为空（基于图像的图标）。	iconsdir
`directory path url ex. ./images/icons`	Yes	No	非基于字体的图像图标的位置。如果指定了`imagesdir`而未指定`iconsdir`，则默认为`imagesdir`下的_icons_文件夹。	icontype
`jpg (png) gif svg`	No	No	图像图标的文件类型。仅在使用基于图像的图标时相关。	imagesdir

参数名

参数值

默认值

是否必填

说明

+

:---

:---

iconfont-cdn

网址

+ (默认的CDN网址)

No

Yes

如果不特别指定，将使用cdnjs.com服务。用于覆盖链接至Font Awesome样式表的CDN。

iconfont-name

任意值

+ (font-awesome)

Yes

用于覆盖图标字体样式表的名称。

iconfont-remote

empty

Yes

允许使用CDN来解析图标字体。仅当`icons`属性的值为`font`时相关。

icons

empty[=image] image font

Yes

选择使用图像或字体图标替代文本进行警告。任何其他值被视为icontype，并将值设置为空（基于图像的图标）。

iconsdir

directory path url ex. ./images/icons

Yes

非基于字体的图像图标的位置。如果指定了`imagesdir`而未指定`iconsdir`，则默认为`imagesdir`下的_icons_文件夹。

icontype

jpg (png) gif svg

图像图标的文件类型。仅在使用基于图像的图标时相关。

imagesdir

源代码高亮和格式化属性

.名称允许的值默认设置仅限表头注释

.名称	允许的值	默认设置	仅限表头	注释
`coderay-css`	(`class`) `style`	No	Yes	控制 CodeRay 是使用 CSS 类还是行内样式。
`coderay-linenums-mode`	`inline` (`table`)	No	No	设置 CodeRay 如何在源代码列表中插入行号。
`coderay-unavailable`	empty	No	Yes	指示处理器不加载 CodeRay。如果处理器加载 CodeRay 失败也会设置此项。
`highlightjsdir`	directory path url (default CDN URL)	No	Yes	设置 highlight.js 源代码高亮库的位置。
`highlightjs-theme`	highlight.js style name (`github`)	No	Yes	highlight.js 使用的主题名称。
`prettifydir`	directory path url (default CDN URL)	No	Yes	设置非 CDN prettify 源代码高亮库的位置。
`prettify-theme`	prettify style name (`prettify`)	No	Yes	prettify 使用的主题名称。
`prewrap`	*empty*	Yes	No	包装宽代码列表。
`pygments-css`	(`class`) `style`	No	Yes	控制 Pygments 是使用 CSS 类还是行内样式。
`pygments-linenums-mode`	(`table`) `inline`	No	No	设置 Pygments 如何在源代码列表中插入行号。
`pygments-style`	Pygments style name (`default`)	No	Yes	Pygments 使用的风格名称。
`pygments-unavailable`	empty	No	Yes	指示处理器不加载 Pygments。如果处理器加载 Pygments 失败也会设置此项。
`rouge-css`	(`class`) `style`	No	Yes	控制 Rouge 是使用 CSS 类还是行内样式。
`rouge-linenums-mode`	`inline` (`table`)	No	No	设置 Rouge 如何在源代码列表中插入行号。 `inline` 目前尚未被 Asciidoctor 支持。参见 asciidoctor#3641。
`rouge-style`	Rouge style name (`github`)	No	Yes	Rouge 使用的风格名称。
`rouge-unavailable`	empty	No	Yes	指示处理器不加载 Rouge。如果处理器加载 Rouge 失败也会设置此项。
`source-highlighter`	`coderay` `highlight.js` `pygments` `rouge`	No	Yes	指定源代码高亮器。其他任何值都是允许的，但必须由自定义的语法高亮器适配器支持。
`source-indent`	integer	No	No	在源代码列表中标准化块缩进。
`source-language`	源代码语言名称	No	No	默认语言用于源代码块。
`source-linenums-option`	空	No	No	为源代码列表开启行号。

coderay-css

(class)
style

Yes

控制 CodeRay 是使用 CSS 类还是行内样式。

coderay-linenums-mode

inline
(table)

设置 CodeRay 如何在源代码列表中插入行号。

coderay-unavailable

empty

Yes

指示处理器不加载 CodeRay。如果处理器加载 CodeRay 失败也会设置此项。

highlightjsdir

directory path
url
(default CDN URL)

Yes

设置 highlight.js 源代码高亮库的位置。

highlightjs-theme

highlight.js style name
(github)

Yes

highlight.js 使用的主题名称。

prettifydir

directory path
url
(default CDN URL)

Yes

设置非 CDN prettify 源代码高亮库的位置。

prettify-theme

prettify style name
(prettify)

Yes

prettify 使用的主题名称。

prewrap

empty

Yes

包装宽代码列表。

pygments-css

(class)
style

Yes

控制 Pygments 是使用 CSS 类还是行内样式。

pygments-linenums-mode

(table)
inline

设置 Pygments 如何在源代码列表中插入行号。

pygments-style

Pygments style name
(default)

Yes

Pygments 使用的风格名称。

pygments-unavailable

empty

Yes

指示处理器不加载 Pygments。如果处理器加载 Pygments 失败也会设置此项。

rouge-css

(class)
style

Yes

控制 Rouge 是使用 CSS 类还是行内样式。

rouge-linenums-mode

inline
(table)

设置 Rouge 如何在源代码列表中插入行号。 `inline` 目前尚未被 Asciidoctor 支持。 参见 asciidoctor#3641。

rouge-style

Rouge style name
(github)

Yes

Rouge 使用的风格名称。

rouge-unavailable

empty

Yes

指示处理器不加载 Rouge。如果处理器加载 Rouge 失败也会设置此项。

source-highlighter

coderay
highlight.js
pygments
rouge

Yes

指定源代码高亮器。其他任何值都是允许的，但必须由自定义的语法高亮器适配器支持。

source-indent

integer

在源代码列表中标准化块缩进。

source-language

源代码语言名称

默认语言用于源代码块。

source-linenums-option

空

为源代码列表开启行号。

HTML样式属性

.名称

允许的值

默认设置

仅限表头

注释

复制CSS文件到输出路径。仅在设置了`linkcss`属性时相关。

css-signature

valid XML ID

Yes

Assign value to id attribute of HTML <body> element. Preferred approach is to assign an ID to document title.

linkcss

empty

Yes

Links to stylesheet instead of embedding it. Can’t be unset in SECURE mode.

max-width

CSS 长度（例如 55em, 12cm 等）

Yes

限制文档正文的最大宽度。不推荐。请改用 CSS 样式表。

stylesdir

目录路径
url
.

Yes

CSS 样式表的位置。

样式表

空白文件路径

Yes

CSS样式表文件名。若值为空，则告诉转换器使用默认的样式表。

toc-class

手册页属性

本节中的属性仅在使用manpage文档类型和/或后端时相关。

.名称允许的值默认设置仅限表头注释

.名称	允许的值	默认设置	仅限表头	注释
`mantitle`	任意	基于内容。	Yes	用于手册页输出的元数据。基于内容的手册页输出元数据。
`manname`	any	基于内容。	Yes	man页面输出的元数据。根据内容为man页面输出的元数据。 '''
`man-linkstyle`	link format pattern (`blue R <>`)	No	Yes	Link style in man page output.''' 翻译成中文是： '''
`man页面链接样式`	链接格式模式 (`蓝色 R <>`)	No	Yes	man页面输出中的链接样式。'''
`mansource`	any	No	Yes	Source (e.g., application and version) the man page describes.
`manmanual`	any	No	Yes	Manual name displayed in the man page footer.` 在man手册页脚显示的手册名称。

mantitle

任意

基于内容。

Yes

用于手册页输出的元数据。

基于内容的手册页输出元数据。

manname

any

基于内容。

Yes

man页面输出的元数据。

根据内容为man页面输出的元数据。

'''

man-linkstyle

link format pattern
(blue R <>)

Yes

Link style in man page output.''' 翻译成中文是：

'''

man页面链接样式

链接格式模式
(蓝色 R <>)

Yes

man页面输出中的链接样式。'''

mansource

any

Yes

Source (e.g., application and version) the man page describes.

manmanual

any

Yes

Manual name displayed in the man page footer.` 在man手册页脚显示的手册名称。

安全属性

由于这些属性涉及安全问题，它们只能通过API或CLI设置。

.名称

允许的值

默认设置

仅API/CLI

备注

允许从URL读取数据。

max-attribute-value-size

integer (≥ 0)
4096

如果安全模式为SECURE

Yes

限制解析后的属性值的最大大小（字节为单位）。默认值仅在SECURE模式下设置。由于属性可以引用属性，如果没有这个限制，可能会创建一个相对于输入文档大得多的输出文档。

max-include-depth

integer (≥ 0)
64

Yes

限制无限包含循环，并且限制利用嵌套包含来增加输出文档大小的机会。

^[1]` -number 属性是由 AsciiDoc 处理器自动创建和管理的，专门用于带编号的块。仅在相应的 -caption 属性设置（例如，listing-caption）并且块有标题时使用。在 Asciidoctor 中，设置 -number 属性将会影响随后同类型编号块的下一个使用的数字。然而，你不应该依赖这种行为，因为它可能会在该语言未来的修订中改变。