Document attributes are used either to configure behavior in the processor or to relay information about the document and its environment.
This page catalogs all the built-in (i.e., reserved) document attributes in AsciiDoc.
...
...
@@ -23,10 +24,10 @@ Numeric values and values shown in _italic_ are instructional and indicate a val
The attribute is simply turned on by being set.
* _empty_[=`effective`] -- In some cases, an empty value is interpreted by the processor as one of the allowable non-empty values.
This effective value is prefixed with an equals sign and enclosed in square brackets (e.g., [=`auto`]).
The effective value will not be visible to an attribute reference.
An attribute reference will resolve to an empty value rather than the effective value.
* (`implied`) -- Built-in attributes that are not set may have an implied value.
The implied value is enclosed in parentheses (e.g., (`attributes`)).
An implied value cannot be resolved using an attribute reference.
An implied value can't be resolved using an attribute reference.
+
If the attribute doesn't accept _any_ or _empty_, than you must only assign one of the allowable values or specified value type.
...
...
@@ -36,6 +37,229 @@ Otherwise, the assignment won't have any effect on the document.
If an attribute is not marked as _Header Only_, it can be set anywhere in the document, assuming the attribute is not locked by the API or CLI.
However, changing an attribute only affects behavior for content that follows the assignment (in document order).
== Intrinsic attributes
Intrinsic attributes are set automatically by the processor.
These attributes provide information about the document being processed (e.g., `docfile`), the security mode under which the processor is running (e.g., `safe-mode-name`), and information about the user's environment (e.g., `user-home`).
Many of these attributes are read only, which means they can't be modified (with some exceptions).
Attributes which are not are marked as modifiable.
Attributes marked as both modifiable and API/CLI Only can only be set from the API or CLI.
All other attributes marked as modifiable must be set by the end of the header (i.e., Header Only).
[cols="30m,20,^10,^10,30"]
|===
.>|Name .>|Allowable Values .>|Modifiable .>|API/CLI Only .>|Notes
|backend
|_any_ +
_ex._ html5
|{y}
|{n}
|The backend used to select and activate the converter that creates the output file.
Usually named according to the output format (e.g., `html5`)
|basebackend
|_any_ +
_ex._ html
|{n}
|n/a
|The generic backend on which the backend is based.
Typically derived from the backend value minus trailing numbers (e.g., the basebackend for `docbook5` is `docbook`).
May also indicate the internal backend employed by the converter (e.g., the basebackend for `pdf` is `html`).
|docdate
|_date (ISO)_ +
_ex._ 2019-01-04
|{y}
|{n}
|Last modified date of the source document.^[<<note-docdatetime,1>>,<<note-sourcedateepoch,2>>]^
|docdatetime
|_datetime (ISO)_ +
_ex._ 2019-01-04 19:26:06 UTC
|{y}
|{n}
|Last modified date and time of the source document.^[<<note-docdatetime,1>>,<<note-sourcedateepoch,2>>]^
|docdir
|_directory path_ +
_ex._ /home/user/docs
|If input is a string
|{y}
|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
|{y}
|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
|{y}
|File extension of the source document, including the leading period.
|docname
|_file stem basename_ +
_ex._ userguide
|If input is a string
|{y}
|Root name of the source document (no leading path or file extension).
|doctime
|_time (ISO)_ +
_ex._ 19:26:06 UTC
|{y}
|{n}
|Last modified time of the source document.^[<<note-docdatetime,1>>,<<note-sourcedateepoch,2>>]^
|docyear
|_integer_ +
_ex._ {docyear}
|{y}
|{n}
|Year that the document was last modified.^[<<note-docdatetime,1>>,<<note-sourcedateepoch,2>>]^
|embedded
|_empty_
|{n}
|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
|{y}
|File extension of the output file name (without leading period).
|htmlsyntax
|`html` +
`xml`
|{n}
|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
|{y}
|{n}
|Date when the document was converted.^[<<note-sourcedateepoch,2>>]^
|localdatetime
|_datetime (ISO)_ +
_ex._ 2019-02-17 19:31:05 UTC
|{y}
|{n}
|Date and time when the document was converted.^[<<note-sourcedateepoch,2>>]^
|localtime
|_time (ISO)_ +
_ex._ 19:31:05 UTC
|{y}
|{n}
|Time when the document was converted.^[<<note-sourcedateepoch,2>>]^
|localyear
|_integer_ +
_ex._ {localyear}
|{y}
|{n}
|Year when the document was converted.^[<<note-sourcedateepoch,2>>]^
|outdir
|_directory path_ +
_ex._ /home/user/docs/dist
|{n}
|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}
|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
|{y}
|{n}
|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}
|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}
|n/a
|Textual value of the safe mode setting.
|safe-mode-unsafe
|_empty_
|{n}
|n/a
|Set if the safe mode is UNSAFE.
|safe-mode-safe
|_empty_
|{n}
|n/a
|Set if the safe mode is SAFE.
|safe-mode-server
|_empty_
|{n}
|n/a
|Set if the safe mode is SERVER.
|safe-mode-secure
|_empty_
|{n}
|n/a
|Set if the safe mode is SECURE.
|user-home
|_directory path_ +
_ex._ /home/user
|{n}
|n/a
|Full path of the home directory for the current user.
Masked as `.` if the safe mode is SERVER or SECURE.
|===
[[note-docdatetime]]^[1]^ Only reflects the last modified time of the source document file.
It does not consider the last modified time of files which are included.
[[note-sourcedateepoch]]^[2]^ If the SOURCE_DATE_EPOCH environment variable is set, the value assigned to this attribute is built from a UTC date object that corresponds to the timestamp (as an integer) stored in that environment variable.
This override offers one way to make the conversion reproducible.
See the {url-epoch}[source date epoch specification] for more information about the SOURCE_DATE_EPOCH environment variable.
Otherwise, the date is expressed in the local time zone, which is reported as a time zone offset (e.g., `-0600`) or UTC if the time zone offset is 0).
To force the use of UTC, set the `TZ=UTC` environment variable when invoking Asciidoctor.
== Compliance attributes
[cols="30m,20,^10,^10,30"]
...
...
@@ -105,7 +329,7 @@ Useful for storing the output in a source code control system as it prevents spu
(`@`)
|{n}
|{n}
|Sets the seed value for the appendix number sequence.^[<<fn-number,1>>]^
|Sets the seed value for the appendix number sequence.^[<<note-number,1>>]^
|appendix-refsig
|_any_ +
...
...
@@ -123,10 +347,10 @@ Useful for storing the output in a source code control system as it prevents spu
|chapter-number
|_number_ +
(0)
(`0`)
|{n}
|{n}
|Sets the seed value for the chapter number sequence.^[<<fn-number,1>>]^
|Sets the seed value for the chapter number sequence.^[<<note-number,1>>]^
_Book doctype only_.
|chapter-refsig
...
...
@@ -153,10 +377,10 @@ _Book doctype only_.
|example-number
|_number_ +
(0)
(`0`)
|{n}
|{n}
|Sets the seed value for the example number sequence.^[<<fn-number,1>>]^
|Sets the seed value for the example number sequence.^[<<note-number,1>>]^
|figure-caption
|_any_ +
...
...
@@ -167,10 +391,10 @@ _Book doctype only_.
|figure-number
|_number_ +
(0)
(`0`)
|{n}
|{n}
|Sets the seed value for the figure number sequence.^[<<fn-number,1>>]^
|Sets the seed value for the figure number sequence.^[<<note-number,1>>]^
|important-caption
|_any_ +
...
...
@@ -201,10 +425,10 @@ _Book doctype only_.
|listing-number
|_number_ +
(0)
(`0`)
|{n}
|{n}
|Sets the seed value for the listing number sequence.^[<<fn-number,1>>]^
|Sets the seed value for the listing number sequence.^[<<note-number,1>>]^
|manname-title
|_any_ +
...
...
@@ -263,10 +487,10 @@ _Book doctype only_.
|table-number
|_number_ +
(0)
(`0`)
|{n}
|{n}
|Sets the seed value for the table number sequence.^[<<fn-number,1>>]^
|Sets the seed value for the table number sequence.^[<<note-number,1>>]^
|tip-caption
|_any_ +
...
...
@@ -451,7 +675,7 @@ See xref:sections:id-prefix-and-separator.adoc#separator[Change the ID word sepa
|{startsb}+-{endsb}0{endash}5
|{n}
|{n}
|Increases or decreases level of headings in include files.
|Increases or decreases level of headings below assignment.
A leading + or - makes the value relative.
//<<include-partitioning>>
...
...
@@ -459,7 +683,8 @@ A leading + or - makes the value relative.
The AsciiDoc processor automatically assigns values to various document attributes whenever a document is loaded or converted.
These _intrinsic attributes_ provide information about the document being processed (e.g., `docfile`), the security mode under which the processor is running (e.g., `safe-mode-name`), and some information about the user's environment (e.g., `user-home`).
Like all document attributes, the value of an intrinsic attributes can be accessed using an attribute reference.
Many of these attributes are intended to be read only.
// tag::table[]
[#env-attributes-table%autowidth,cols="~m,~,~m"]
|===
|Attribute |Description |Example Value
//|asciidoctor
//|Set if the current processor is Asciidoctor.
//|{asciidoctor}
//
//|asciidoctor-version
//|Asciidoctor version.
//|{asciidoctor-version}
|backend
|The backend used to select and activate the converter that creates the output file.
Usually named according to the output format (e.g., `html5`)
|html5
|basebackend
|The generic backend on which the backend is based.
Typically the backend value minus any trailing numbers (e.g., the basebackend for `docbook5` is `docbook`).
May also indicate the internal backend employed by the converter (e.g., the basebackend for `pdf` is `html`).
|html
|docdate
|Last modified date of the source document.^[<<note_docdatetime,1>>,<<note_sourcedateepoch,2>>]^
|2019-01-04
|docdatetime
|Last modified date and time of the source document.^[<<note_docdatetime,1>>,<<note_sourcedateepoch,2>>]^
|2019-01-04 19:26:06 UTC
|docdir
|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).
|/home/user/docs
|docfile
|Full path of the source document.
Truncated to the basename if the safe mode is SERVER or SECURE (to conceal the file's location).
|/home/user/docs/userguide.adoc
|docfilesuffix
|File extension of the source document, including the leading period.
|.adoc
|docname
|Root name of the source document (no leading path or file extension).
|userguide
|doctime
|Last modified time of the source document.^[<<note_docdatetime,1>>,<<note_sourcedateepoch,2>>]^
|19:26:06 UTC
|doctype
|Document type (article, book, inline, or manpage).
|article
|docyear
|Year that the document was last modified.^[<<note_docdatetime,1>>,<<note_sourcedateepoch,2>>]^
|{docyear}
|embedded
|Set if content is being converted to an embedded document (i.e., body of document only).
|
|filetype
|File extension of the output file name (without leading period).
|html
|htmlsyntax
|Syntax used when generating the HTML output (html or xhtml).
|html
|localdate
|Date when the document was converted.^[<<note_sourcedateepoch,2>>]^
|2019-02-17
|localdatetime
|Date and time when the document was converted.^[<<note_sourcedateepoch,2>>]^
|2019-02-17 19:31:05 UTC
|localtime
|Time when the document was converted.^[<<note_sourcedateepoch,2>>]^
|19:31:05 UTC
|localyear
|Year when the document was converted.^[<<note_sourcedateepoch,2>>]^
|{localyear}
|outdir
|Full path of the output directory.
(Cannot be referenced in the content.
Only available to the API once the document is converted).
|/home/user/docs/dist
|outfile
|Full path of the output file.
(Cannot be referenced in the content.
Only available to the API once the document is converted).
