Skip to content
Snippets Groups Projects
Commit fb2a25d8 authored by Sarah White's avatar Sarah White Committed by Dan Allen
Browse files

migrate documentation for the AsciiDoc language

parents
No related branches found
No related tags found
No related merge requests found
Showing
with 1388 additions and 0 deletions
= Set and Define Custom Document Attributes
// [#set-user-defined]
//If you're familiar with writing in XML, you might recognize a document attribute as a user-defined entity.
When you find yourself typing the same text repeatedly, or text that often needs to be updated, consider creating your own attribute.
[#user-defined-names]
== User-defined attribute names and values
A user-defined attributes must have a name and explicitly assigned value.
The attribute's name must:
* be at least one character long,
* begin with a word character (A-Z, a-z, 0-9, or _), and
* only contain word characters and hyphens.
The name cannot contain dots or spaces.
Although uppercase characters are permitted in an attribute name, the name is converted to lowercase before being stored.
For example, `URL` and `Url` are treated as `url`.
A best practice is to only use lowercase letters in the name and avoid starting the name with a number.
[[user-values]]Attribute values can:
* be any inline content, and
* contain line breaks, but only if an xref:wrap-values.adoc#hard[explicit line continuation] (`+`) is used.
== Create a custom attribute and value
A prime use case for attribute entries is to promote frequently used text and URLs to the top of the document.
.Create a user-defined attribute and value
[source#ex-user-set]
----
:disclaimer: Don't pet the wild Wolpertingers. If you let them into your system, we're \ <.>
not responsible for any loss of hair, chocolate, or purple socks.
:url-repo: https://github.com/asciidoctor/asciidoctor
----
<.> Long values can be xref:wrap-values.adoc[soft wrapped] using a backslash (`\`).
Now, you can xref:reference-custom-attributes.adoc[reference these attributes] throughout the document.
= Get Started with Document Attributes
You can think of a document attribute as a global variable for the AsciiDoc language.
== What are document attributes?
Document attributes are a powerful text replacement tool and means of controlling built-in settings and behavior for a whole document or regions of a document.
Document attributes:
* Turn on or turn off built-in features
* Configure built-in features
* Declare built-in asset locations
* Hold content for reuse throughout a document
== Types of document attributes
Document attributes fall into the following groups.
Built-in attributes:: Built-in attributes add, configure, and control common features in a document.
Many built-in attributes only take effect when defined in the document header with an attribute entry.
Boolean attributes:: Boolean attributes are a subgroup of the built-in attribute.
They don't have an explicitly assigned value because they act like a toggle.
Their sole function is to turn on or turn off a feature.
User-defined attributes:: #TBA#
== What does setting a document attribute mean?
* be set (turned on)
== What does defining a document attribute mean?
* have default values in the case of built-in attributes
* have no value in the case of boolean attributes and built-in attributes with default values
* have a single line value
* have a value that xref:wrap-values.adoc[spans multiple, contiguous lines]
* have a value that includes basic inline AsciiDoc syntax, such as:
** attribute references
** text formatting (if wrapped in a xref:pass:pass-macro.adoc#pass-subs[pass macro])
** inline macros (if wrapped in a xref:pass:pass-macro.adoc#pass-subs[pass macro])
But there are certain limitations to be aware of.
Document attributes cannot:
* have a value that includes AsciiDoc block content, such as:
** lists
** multiple paragraphs
** blocks (tables, sidebars, examples, etc)
** other whitespace-dependent markup
== What does unsetting a document attribute mean?
* be unset (turned off) with a leading (preferred) or trailing `!` added to the name
== Where are document attributes set, defined, and unset?
Document attributes can be declared in the:
* document header as an xref:attribute-entries.adoc[attribute entry]
* document body as an xref:attribute-entries.adoc[attribute entry]
* API via the `:attributes` option
* CLI via the `-a` option
* override locked attributes assigned from the command line
== What does referencing a document attribute mean?
TBA
== Where can document attributes be referenced?
TBA
////
== Handling a missing attribute
If you use an attribute that xref:handle-unresolved-ref.adoc[is not defined], you can specify how Asciidoctor handles attribute reference errors.
////
= Get Started with Element Attributes
Element attributes are a powerful means of controlling the built-in settings of individual block and inline elements.
They're also used to apply user-defined behavior and supplemental information, such as citation information and fallback content, to certain elements.
== What are element attributes?
[.term]*Element attributes* define the built-in and user-defined styles, behavior, and metadata that are applied to an individual xref:ROOT:elements.adoc#block[block element] or xref:ROOT:elements.adoc#inline[inline element] in a document.
Element attributes:
* Declare the style and ID of an element
* Turn on or turn off an individual element's built-in features
* Configure the built-in features of an individual element
* Apply user-defined information, such as citation metadata, fallback text, link text, and target content, to an individual element
* Apply user-defined roles and behaviors to an individual element
They're set and defined directly on the element they're modifying using an attribute list.
Element attributes are classified as positional or named.
Attributes can be assigned to individual elements in a document using an attribute list.
[#attribute-list]
== Attribute lists
Attributes are assigned to block and inline elements using an [.term]*attribute list*.
Attribute lists:
* apply to blocks, macros, and inline elements
* can contain xref:positional-and-named-attributes.adoc[positional and named attributes]
* take precedence over xref:document-attributes.adoc[document attributes] (attribute entries)
.Anatomy of an attribute list
[positional_attribute_1,positional_attribute_2,named_attribute="value"]
= Get Started with Attributes
Attributes set AsciiDoc apart from other lightweight markup languages.
Attributes activate behaviors, styles, and integrations, or hold replacement (variable) content.
There are three types of attributes: document, element, and environment.
Document attributes:: xref:document-attributes.adoc[Document attributes] apply built-in behavior and settings to a whole document, or in select cases, to regions of a document.
They make user-defined information available for use throughout a whole document.
They're set and defined in a document's header using an attribute entry, but can also be used from the API or command line.
Element attributes:: xref:element-attributes.adoc[Element attributes] apply built-in and user-defined styles, metadata, and behavior to individual block and inline elements in a document.
They're set and defined directly on the element they're modifying using an attribute list.
Element attributes are classified as positional or named.
Environment attributes:: Environment attributes provide information about the runtime environment, such as how, where, and when a document is being processed.
Environment attributes are built-in and Asciidoctor automatically sets and assigns them values when a document is loaded or converted.
Environment attributes can be referenced wherever attribute references are permitted, but it's recommended that you treat these attributes as read only.
= The ID Attribute
The `id` attribute specifies a unique name for an element.
That name can only be used once in a document.
An ID:
. provides an internal link or cross reference anchor for an element, and
. references an optional style or behavior used by the output processor.
////
BlockId
NOTE: Section pending
////
== Block assignment
// tag::bl[]
In an attribute list, there are two ways to assign the `id` attribute to a block.
. Prefixing the name with a hash (`#`).
. Specifying the name with `id=name`.
[source]
----
[#goals]
* Goal 1
* Goal 2
----
Let's say you want to create a blockquote from an open block and assign it an ID and role.
You add `quote` (the block style) in front of the `#` (the ID) in the first attribute position, as this example shows:
[source]
----
[quote#roads, Dr. Emmett Brown]
____
Roads? Where we're going, we don't need roads.
____
----
TIP: The order of ID and role values in the shorthand syntax does not matter.
CAUTION: If the ID contains a `.`, you must define it using either a longhand assignment (e.g., `id=classname.propertyname`) or the anchor shorthand (e.g., `+[[classname.propertyname]]+`).
This is necessary since the `.` character in the shorthand syntax is the delimiter for a role, and thus gets misinterpreted as such.
// end::bl[]
== Inline assignment
// tag::in[]
The id (`#`) shorthand can be used on inline quoted text.
.Quoted text block with id assignment using shorthand syntax
----
[#free_the_world]*free the world*
----
// end::in[]
////
.Quoted text block with `id` assignment using traditional AsciiDoc syntax
----
[[free_the_world]]*free the world*
----
////
[#anchor]
== Use an ID as an anchor
//um anchor: anchordef
An anchor (aka ID) can be defined almost anywhere in the document, including on section title, on a discrete heading, on a paragraph, on an image, on a delimited block, on an inline phrase, and so forth.
The anchor is declared by enclosing a _valid_ XML Name in double square brackets (e.g., `+[[idname]]+`) or using the shorthand ID syntax (e.g., `[#idname]`) at the start of an attribute list.
The double square bracket form requires the ID to start with a letter, an underscore, or a colon, ensuring the ID is portable.
According to the https://www.w3.org/TR/REC-xml/#NT-Name[XML Name] rules, a portable ID may not begin with a number, even though a number is allowed elsewhere in the name.
The shorthand form in an attribute list does not impose this restriction.
If you want to reference a block element, all you need to do is assign an ID to that block.
You can enclose the ID in double square brackets:
.Assign an ID to a paragraph
[source]
----
include::example$id.adoc[tag=block-id-brackets]
----
or use the shorthand ID syntax:
.Assign an ID to a paragraph using shorthand syntax
[source]
----
include::example$id.adoc[tag=block-id-shorthand]
----
You can also define an anchor anywhere in content that receives normal substitutions (specifically the macro substitution).
You can enclose the ID in double square brackets:
.Define an inline anchor
[source]
----
include::example$id.adoc[tag=anchor-brackets]
----
or using the shorthand ID syntax.
.Define an inline anchor using shorthand syntax
[source]
----
include::example$id.adoc[tag=anchor-shorthand]
----
In addition to being able to define anchors on sections and blocks, anchors can be defined inline where ever you can type normal text (anchors are a macro substitution).
The anchors in the text get replaced with invisible anchor points in the output.
For example, you would not put an anchor in front of a list item:
.Wrong position for an anchor ID in front of a list item.
[source]
----
include::example$id.adoc[tag=anchor-wrong]
----
Instead, you would put it at the very start of the text of the list item:
.Define an inline anchor on a list item
[source]
----
include::example$id.adoc[tag=anchor-list]
----
Here's how you can define the ID for a section using an inline anchor:
.Define the ID of a section using an inline anchor
[source]
----
include::example$id.adoc[tag=anchor-header]
----
To add additional anchors to a section, place them in front of the title.
.Add additional anchors to a section
[source]
----
include::example$id.adoc[tag=anchor-header-extra]
----
CAUTION: If you add additional anchors to a section title, make sure you also assign an explicit ID to that section.
Otherwise, the anchor tag gets caught up in the generated ID.
//See {issue-ref}/840[#840] for details.
Remember that inline anchors are discovered where ever the macro substitution is applied (e.g., paragraph text).
If text content doesn't belong somewhere, neither does an inline anchor point.
// TODO introduce a subsection here
It's possible to customize the text that will be used in the cross reference link (called `xreflabel`).
If not defined, Asciidoctor does it best to find suitable text (the solution differs from case to case).
In case of an image, the image caption will be used.
In case of a section header, the text of the section's title will be used.
To define the `xreflabel`, add it in the anchor definition right after the ID (separated by a comma).
.An anchor ID with a defined xreflabel. The caption will not be used as link text.
[source]
----
include::example$id.adoc[tag=anchor-xreflabel]
----
Instead of the bracket form, you can use the macro `anchor` to achieve the same goal.
.Setting an anchor ID using the macro form
[source]
----
include::example$id.adoc[tag=anchor-macro]
----
= Inline Attribute Entries
In places where document attribute entry lines are not normally processed, such as in a table cell, document attributes can be assigned using the following syntax:
[source]
{set:name[!]:[value]}
For example:
[source]
{set:sourcedir:src/main/java}
is effectively the same as:
[source]
:sourcedir: src/main/java
= Attribute Entry Names and Values
== Valid built-in names
Built-in attribute names are reserved and can't be re-purposed for user-defined attribute names.
The built-in attribute names are listed in the xref:ref-document.adoc[] and xref:ref-character-replacement.adoc[].
[#user-defined]
== Valid user-defined names
User-defined attribute names must:
* be at least one character long,
* begin with a word character (a-z, 0-9, or _), and
* only contain word characters and hyphens (-).
A user-defined attribute name cannot contain dots (.) or spaces.
Although uppercase characters are permitted in an attribute name, the name is converted to lowercase before being stored.
For example, `URL-REPO` and `URL-Repo` are treated as `url-repo` when a document is loaded or converted.
A best practice is to only use lowercase letters in the name and avoid starting the name with a number.
== Attribute value types and assignment methods
Depending on the attribute, its value may be an empty string, an integer such as 5 or 2, or a string of characters like your name or a URL.
Attributes that accept string values may include references to other attributes and inline macros.
Values can't contain complex, multi-line block elements such as tables or sidebars.
An attribute's value may be assigned by default when the value is left empty in an attribute entry or the value may be assigned explicitly by the user.
The type of value an attribute accepts and whether it uses a default value, has multiple built-in values, accepts a user-defined value, or requires a value to be explicitly assigned depends on the attribute.
=== Built-in values
Many built-in attributes have one or more built-in values.
One of these values may be designated as the attribute's default value.
Asciidoctor will fall back to this default value if you set the attribute but leave the value blank.
Additionally, Asciidoctor automatically sets numerous built-in attributes at processing time and assigns them their default values unless you explicitly unset the attribute or assign it another value.
For instance, Asciidoctor automatically sets all of the xref:ref-character-replacement.adoc[character replacement attributes].
If you want to use the non-default value of a built-in attribute, you need to set it and assign it an alternative value.
=== Empty string values
The value for built-in boolean attributes is always left empty in an attribute entry since these attributes only turn on or turn off a feature.
During processing, Asciidoctor assigns any activated boolean attributes an _empty string_ value.
=== Explicit values
You must explicitly assign a value to an attribute when:
* it doesn't have a default value,
* you want to override the default value, or
* it's a user-defined attribute.
The type of explicit value a built-in attribute accepts depends on the attribute.
User-defined attributes accept string values.
Long explicit values can be xref:wrap-values.adoc[wrapped].
////
For example,
[source]
----
:keywords: content engineering, branch collisions, 42, {meta-topics}, FTW <1> <2>
----
<1> The xref:header:metadata.adoc#keywords[built-in keywords attribute] doesn't have a default value, so you must explicitly assign it a value when you set it.
<2> Attributes that accept string values may include <<attribute-reference,references to other attributes>>, e.g, `+{meta-topics}+`.
See the xref:ref-document.adoc[Document Attributes Reference] for information about each built-in attribute's accepted value types.
You must explicitly assign a value to a built-in attribute when you want to override its default value.
For instance, when a section in a document is assigned the appendix style, that section title will be automatically prefixed with a label and a letter that signifies that section's order, e.g., Appendix A, by default.
Let's override the default letter ordering and use a number instead.
[source]
----
:appendix-number: 1
----
Now the first section assigned the appendix style will be prefixed Appendix 1, the second, Appendix 2, and so forth.
=== User-defined values
The value field of a built-in attribute is left blank if it's a boolean attribute.
The value can also be left blank if the attribute has a default value and that's the value you want to assign to it.
When you're setting a built-in attribute, the value may be _empty string_ if it's a boolean attribute, a built-in value, or a user-defined value.
However, if the document attribute is built-in, the value may be _empty
Depending on the type of document attribute--built-in or user-defined--the value may be _empty string_,
Some attributes may not have a value explicitly assigned to them.
When a value is not specified, the value _empty string_ is assumed.
An empty value is often used to set a boolean attribute (thus making a blank value implicitly true).
* it's a built-in attribute doesn't accept any explicitly set values because it only turns on a behavior,
* it's a built-in attribute that uses a default value when its value is left empty, or
* the attribute was set, but not assigned a value by accident.
In this case, it will use its default value if applicable or output an error message when the document is processed.
////
= The Options Attribute
The `options` attribute is a versatile xref:positional-and-named-attributes.adoc#named[named attribute] that can be assigned one or more values.
It can be defined globally as document attribute as well as a block attribute on an individual block.
== Assign options to blocks
You can assign one or more options to a block using the shorthand or formal syntax for the `options` attribute.
=== Shorthand options syntax for blocks
To assign an option to a block, prefix the value with a percent sign (`%`) in an attribute list.
The percent sign implicitly sets the `options` attribute.
.Sidebar block with an option assigned using the shorthand dot
[source#ex-block]
----
[%value]
****
This is a sidebar with an option assigned to it.
****
----
You can assign multiple options to a block by prefixing each value with a percent sign (`%`).
.Sidebar with two options assigned using the shorthand dot
[source#ex-two-options]
----
[%value%value]
****
This is a sidebar with two options assigned to it.
****
----
For instance, consider a table with the three built-in option values, `header`, `footer`, and `autowidth`, assigned to it.
<<ex-table-short>> shows how the values are assigned using the shorthand notation.
.Table assigned three options using the shorthand syntax
[source#ex-table-short]
----
[%header%footer%autowidth,cols="2*"]
|===
|Cell A1 |Cell B1
|Cell A2 |Cell B2
|Cell A3 |Cell B3
|===
----
=== Formal options syntax for blocks
Explicitly set `options` or `opts`, followed by the equals sign (`=`), and then the value in an attribute list.
.Sidebar block with an option assigned using the formal syntax
[source#ex-block-formal]
----
[options="value"]
****
This is a sidebar with an option assigned to it.
****
----
Separate multiple option values with commas (`,`).
.Sidebar with three options assigned using the formal syntax
[source#ex-three-roles-formal]
----
[options="value,value,value"]
****
This is a sidebar with three options assigned to it.
****
----
Let's revisit the table in <<ex-table-short>> that has the three built-in option values, `header`, `footer`, and `autowidth`, assigned to it using the shorthand notation (`%`).
Instead of using the shorthand notation, <<ex-table-formal>> shows how the values are assigned using the formal syntax.
.Table assigned three options using the formal syntax
[source#ex-table-formal]
----
[cols="2*",options="header,footer,autowidth"]
|===
|Cell A1 |Cell B1
|Cell A2 |Cell B2
|Cell A3 |Cell B3
|===
----
== Using options with other attributes
Let's consider `options` when combined with other attributes.
The following example show how to structure an attribute list when you have style, role, and options attributes.
.Shorthand
[source]
----
[horizontal.properties%step] <.> <.> <.>
property 1:: does stuff
property 2:: does different stuff
----
<.> xref:styles.adoc[Style is a positional attribute] and its value, in this case `horizontal`, is placed at the start of the attribute list.
<.> `properties` is prefixed with a dot (`.`), signifying that it's assigned to the xref:roles.adoc[role attribute].
The role and options attributes can be set in either order, i.e., `[horizontal%step.properties]`.
<.> The percent sign (`%`) sets the `options` attribute and assigns the `step` value to it.
When you use the formal syntax, the positional and named attributes are separated by commas (`,`).
.Formal
[source]
----
[horizontal,role="properties", options="step"] <.>
property 1:: does stuff
property 2:: does different stuff
----
<.> Like in the shorthand example, named attributes such as `role` and `options` can be set in any order in the attribute list once any xref:positional-and-named-attributes.adoc#positional[positional attributes] are set.
= Positional and Named Attributes
Let's break down the difference between positional and named attributes.
[#positional]
== Positional attribute
// tag::pos[]
Values placed in a specific order in an attribute list don't require an attribute name.
The attribute that the value is assigned to depends on the type of the element:
* `icon:` (1) size
* `image:` and `image::` (1) alt text, (2) width, (3) height
* Delimited blocks: (1) block name (aka style)
* Other inline quoted text: (1) role
For example, the following two image macros are equivalent.
[source]
----
image::sunset.jpg[Sunset,300,400]
image::sunset.jpg[alt=Sunset,width=300,height=400]
----
The second macro is just a duplicate of the first macro written out longhand.
// end::pos[]
[#named]
== Named attribute
// tag::name[]
A named attribute consists of a name and a value separated by an `=` character (e.g., `name=value`).
If the value contains a space, comma, or quote character, it must be enclosed in double or single quotes (e.g., `name="value with space"`).
In all other cases, the surrounding quotes are optional.
If present, the enclosing quotes are dropped from the parsed value.
If the value contains the same quote character used to enclose the value, escape the quote character in the value by prefixing it with a backslash (e.g., `value="the song \"Dark Horse\""`).
[#unset]
=== Unset a named attribute
To undefine a named attribute, set the value to `None` (case sensitive).
// end::name[]
== Substitutions
// tag::subs[]
Attribute references are expanded before the block attribute list is processed.
Therefore, it's not necessary to force substitutions to be applied if you simply want to use a document attribute reference in a block attribute.
If the attribute name (for a positional attribute) or value (for a named attribute) is enclosed in single quotes (e.g., `+title='Processed by https://asciidoctor.org[Asciidoctor]'+`), normal substitutions are applied to the value at assignment time (with some exceptions).
This is also true for positional attributes, such as the attribution for a quote block.
No special processing is performed, except for attribute reference expansion, if the value is not enclosed in quotes or is enclosed in double quotes.
If the attribute value contains the same quote character being used to enclose the value, escape the quote character in the value by prefixing it with a backslash (e.g., `title="\"Dark Horse\" is a song by George Harrison"`).
// end::subs[]
= Character Replacement Attributes Reference
[%autowidth,cols="^m,^l,^"]
|===
|Attribute name |Replacement text |Appearance
|blank
e|nothing
|{empty}
|empty
e|nothing
|{empty}
|sp
e|single space
|{sp}
|nbsp
|&#160;
|{nbsp}
|zwsp^[4]^
|&#8203;
|{zwsp}
|wj^[5]^
|&#8288;
|{wj}
|apos
|&#39;
|{apos}
|quot
|&#34;
|{quot}
|lsquo
|&#8216;
|{lsquo}
|rsquo
|&#8217;
|{rsquo}
|ldquo
|&#8220;
|{ldquo}
|rdquo
|&#8221;
|{rdquo}
|deg
|&#176;
|{deg}
|plus
|&#43;
|{plus}
|brvbar
|&#166;
|&#166;
|vbar
|\|
|{vbar}
|amp
|&
|&
|lt
|<
|<
|gt
|>
|>
|startsb
|[
|[
|endsb
|]
|]
|caret
|^
|^
|asterisk
|*
|*
|tilde
|~
|~
|backslash
|\
|\
|backtick
|`
|`
|two-colons
|::
|::
|two-semicolons
|;;
|;;
|cpp
|C++
|C++
|===
^[1]^ Some replacements are Unicode characters, whereas others are numeric character references (e.g., \&#34;).
These character references are used whenever the use of the Unicode character could interfere with the AsciiDoc syntax or confuse the renderer (i.e., the browser).
It's up to the converter to transform the reference into something the renderer understands (something both the man page and PDF converter handle).
^[2]^ Asciidoctor does not prevent you from reassigning predefined attributes.
However, it's best to treat them as read-only unless the output format requires the use of a different encoding scheme.
These attributes are an effective tool for decoupling content and presentation.
^[3]^ Asciidoctor allows you to use any of the named character references (aka named entities) defined in HTML (e.g., \&euro; resolves to &euro;).
However, using named character references can cause problems when generating non-HTML output such as PDF because the lookup table needed to resolve these names may not be defined.
Our recommendation is avoid using named character references--with the exception of those defined in XML (i.e., lt, gt, amp, quot and apos).
Instead, use numeric character references (e.g., \&#8364;).
^[4]^ The Zero Width Space (ZWSP) is a code point in Unicode that shows where a long word can be split if necessary.
^[5]^ The word joiner (WJ) is a code point in Unicode that prevents a line break at its position.
This diff is collapsed.
= Environment Attributes Reference
:url-epoch: https://reproducible-builds.org/specs/source-date-epoch
Asciidoctor automatically assigns values to various attributes whenever a document is loaded or converted.
These _environment attributes_ provide information about the runtime environment, such as how, where and when the document is being processed.
Like document attributes, environment attributes can be referenced wherever attribute references are permitted.
It's recommended that you treat these attributes as 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 embeddable document (body 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).
|/home/user/docs/dist/userguide.html
|outfilesuffix
|File extension of the output file (starting with a period) as determined by the backend (`.html` for `html`, `.xml` for `docbook`, etc.).
(The value is not updated to match the file extension of the output file when one is specified explicitly).
_Safe to modify._
|.html
|safe-mode-level
|Numeric value of the safe mode setting.
(UNSAFE=0, SAFE=10, SERVER=10, SECURE=20).
|20
|safe-mode-name
|Textual value of the safe mode setting.
|SERVER
|safe-mode-unsafe
|Set if the safe mode is UNSAFE.
|
|safe-mode-safe
|Set if the safe mode is SAFE.
|
|safe-mode-server
|Set if the safe mode is SERVER.
|
|safe-mode-secure
|Set if the safe mode is SECURE.
|
|user-home
|Full path of the home directory for the current user.
Truncated to `.` if the safe mode is SERVER or SECURE.
|/home/user
|===
[[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.
// end::table[]
= Reference Built-in Attributes
You'll likely use the values of certain built-in attributes in specific locations throughout a document.
To reference and use the value of a document attribute, you enclose the attribute's name in curly brackets (`+{name-of-an-attribute}+`).
This inline element is called an *attribute reference*.
== Reference an explicitly set and defined built-in document attribute
TBA
== Reference an automatically set and defined built-in document attribute
An automatically set document attribute is referenced the same way as an explicitly set document attribute.
For instance, Asciidoctor automatically sets all of the character replacement attributes.
That means that you can reference them throughout your document without having to create an attribute entry in its header.
[source]
----
TIP: Wolpertingers don't like temperatures above 100{deg}C. <.>
Our servers don't like them either.
----
<.> Reference the character replacement attribute `deg` by enclosing its name in a set of curly brackets (`+{ }+`).
As you can see below, the attribute reference is replaced with the attribute's value when the document is processed.
TIP: Wolpertingers don't like temperatures above 100{deg}C.
Our servers don't like them either.
= Reference Custom Attributes
:disclaimer: Don't pet the wild Wolpertingers. We're not responsible for any loss \
of hair, chocolate, or purple socks.
:url-repo: https://github.com/asciidoctor/asciidoctor
// [#attribute-reference]
You'll likely use the value of a user-defined attribute entry or certain built-in attributes in specific locations throughout a document.
To reference and use the value of a document attribute, you enclose the attribute's name in curly brackets (`+{name-of-an-attribute}+`).
This inline element is called an *attribute reference*.
== Reference user-defined attributes
Before you can reference an attribute in a document it must be declare using an attribute entry in the document header.
Let's reference the two user-defined attributes set and assigned values in <<ex-user-attrs>>.
.User-defined document attributes set in the document header
[source#ex-user-attrs]
----
= Ops Manual
:disclaimer: Don't pet the wild Wolpertingers. We're not responsible for any loss \
of hair, chocolate, or purple socks.
:url-repo: https://github.com/asciidoctor/asciidoctor
----
Once you've set and assigned a value to the attribute, you can reference that attribute throughout your document.
In <<ex-reference>>, the attribute `url-repo` is referenced twice and `disclaimer` is referenced once.
.User-defined attribute referenced in the document body
[source#ex-reference]
----
Asciidoctor is {url-repo}[open source]. <.>
WARNING: {disclaimer} <.>
If you're missing a lime colored sock, file a ticket in
the {url-repo}/issues[Asciidoctor issue tracker]. <.>
----
<.> Attribute references can be used in macros.
<.> Attribute references can be used in blocks, such as xref:blocks:admonition.adoc[admonitions], and inline.
Since there isn't a blank line between the `disclaimer` reference and the next sentence, the sentence will be directly appended to the end of the attribute's value when it's processed.
<.> The reference to the `url-repo-ex` attribute is inserted into a longer URL address and used in a xref:macros:link.adoc[URL macro].
As you can see below, the attribute references are replaced with the corresponding attribute value when the document is processed.
====
Asciidoctor is {url-repo}[open source].
WARNING: {disclaimer}
If you're missing a lime colored sock, file a ticket in the {url-repo}/issues[Asciidoctor issue tracker].
====
////
To save even more typing, you can store the whole link in an attribute value.
.Link attribute entry
[source]
----
:link-fedpkg: https://apps.fedoraproject.org/packages/rubygem-asciidoctor[Asciidoctor package for Fedora]
----
Now you insert this link anywhere in the document using an attribute reference.
.link-fedpkg attribute usage example
[source]
----
Did you know there's an {link-fedpkg}?
----
Note that the link substitution occurs _after_ the attribute reference is resolved.
This works thanks to the default order of substitutions on a paragraph.
If you want the URL macro to be resolved eagerly at the time the attribute is assigned, you need to enclose it in a pass macro.
.Link attribute entry resolved eagerly
[source]
----
:link-fedpkg: pass:m[https://apps.fedoraproject.org/packages/rubygem-asciidoctor[Asciidoctor package for Fedora]]
----
Now you can use this link in a section title (where the order of substitutions is different).
////
= The Role Attribute
Blocks and many inline elements can be assigned one or more roles using the `role` attribute.
The `role` attribute is a xref:positional-and-named-attributes.adoc#named[named attribute].
You can assign roles to blocks and inline elements using the shorthand dot (`.`) syntax or formal (`role=`) syntax for the `role` attribute.
== Assign roles to blocks
You can assign roles to blocks using the shorthand dot (`.`) syntax or formal (`role=`) syntax for the `role` attribute.
=== Shorthand role syntax for blocks
To assign a role to a block, prefix the value with a dot (`.`) in an attribute list.
The dot implicitly set's the `role` attribute.
.Sidebar block with a role assigned using the shorthand dot
[source#ex-block]
----
[.value]
****
This is a sidebar with a role assigned to it.
****
----
You can assign multiple roles to a block by prefixing each value with a dot (`.`).
.Sidebar with two roles assigned using the shorthand dot
[source#ex-two-roles]
----
[.value.value]
****
This is a sidebar with two roles assigned to it.
****
----
////
[source]
----
[.summary.incremental]
* This is a list with two roles assigned to it.
----
////
=== Formal role syntax for blocks
Explicitly set `role`, followed by the equals sign (`=`), and then the value in an attribute list.
.Sidebar block with a role assigned using the formal syntax
[source#ex-block-formal]
----
[role="value"]
****
This is a sidebar with one role assigned to it.
****
----
Separate multiple role values with commas (`,`).
.Sidebar with two roles assigned using the formal syntax
[source#ex-two-roles-formal]
----
[role="value,value"]
****
This is a sidebar with two roles assigned to it.
****
----
////
[source]
----
[role="summary,incremental"]
* This is a list with two roles assigned to it.
----
////
== Assign roles to formatted inline elements
You can assign roles to inline elements that are enclosed in formatting syntax, such as bold (`+*+`), italic (`+_+`), and monospace (`++`++`).
To assign a role to an inline element that's enclosed in formatting syntax block, prefix the value with a dot (`.`) in an attribute list.
.Inline role assignments using shorthand syntax
[source#ex-role-dot]
----
This sentence contains [.value]*bold inline content* that's assigned a role.
This sentence contains [.value]`monospace text` that's assigned a role.
----
The HTML source code that is output from <<ex-role-dot>> is shown below.
.HTML source code produced by <<ex-role-dot>>
[source#ex-role-html,html]
----
<p>This sentence contains <strong class="value">bold inline content</strong> that&#8217;s assigned a role.</p>
<p>This sentence contains <code class="value">monospace text</code> that&#8217;s assigned a role.</p>
</div>
----
////
Using the shorthand notation, an id can also be specified:
```
[#value.value]`monospace text`
```
which produces:
```html
<a id="value"></a><code class="value">monospace text</code>
```
////
= The Style Attribute
The style attribute is the xref:positional-and-named-attributes.adoc#named[first positional attribute] in an attribute list.
It specifies a predefined set of characteristics to apply to a block or macro.
For example, a paragraph block can be assigned one of the following built-in style attributes:
* normal (default, so does not need to be set)
* literal
* verse
* quote
* listing
* TIP
* NOTE
* IMPORTANT
* WARNING
* CAUTION
* abstract
* partintro
* comment
* example
* sidebar
* source
// Needs examples!
= Handle Unresolved References
When you reference a missing attribute (e.g., `+{does-not-exist}+`), Asciidoctor will leave the attribute reference behind.
If you undefine an attribute on the same line as other text (e.g., `+{set:attribute-no-more!}+`), Asciidoctor will drop the whole line.
You can tailor these behaviors in Asciidoctor using the `attribute-missing` and `attribute-undefined` attributes.
You'll want to think about how you want the processor to handle these situations and configure the processor accordingly.
[#missing]
== Missing attribute
The `attribute-missing` attribute controls how missing references are handled.
By default, missing references are left behind so the integrity of the document is preserved and it's easy for the author to track down.
This attribute has four possible values:
`skip`:: leave the reference in place (default setting)
`drop`:: drop the reference, but not the line
`drop-line`:: drop the line on which the reference occurs (matches behavior of AsciiDoc.py)
`warn`:: print a warning about the missing attribute
The setting you might find of most interest is `warn`, which gives you a warning whenever the processor encounters an attribute reference that cannot be resolved, but otherwise leaves the line alone.
Consider the following line:
[source]
Hello, {name}!
Here's how the line is handled in each case, assuming the `name` attribute is not defined:
[horizontal]
`skip`:: Hello, \{name}!
`drop`:: Hello, !
`drop-line`:: {empty}
`warn`::
+
----
asciidoctor: WARNING: skipping reference to missing attribute: XYZ
----
.History
NOTE: AsciiDoc.py always drops the line that contains a reference to a missing attribute (effectively `attribute-missing=drop-line`).
This "`feature`" was a side effect of how the processor was implemented and not designed with the writer in mind.
The behavior is frustrating for the writer because it's hard to detect where its occurring and can result in loss of important content.
That's why Asciidoctor uses different default behavior and, further, allows the behavior to be customized.
There are a few cases where the `attribute-missing` attribute is not strictly honored.
One of those cases is the include directive.
If a missing attribute is found in the target of an include directive, the processor will issue a warning about the missing attribute and leave behind the same warning message in the converted document.
Another case is the `ifeval` directive.
A missing attribute reference can safely be used in the clause of the `ifeval` directive without any side effects (i.e., `drop`) since the purpose of that statement is to determine whether an attribute resolves to a value.
=== Forcing failure
If you want the processor to fail when the document contains a missing attribute, set the `attribute-missing` attribute to `warn` and pass the `--failure-level=WARN` option to the CLI.
$ asciidoctor -a attribute-missing=warn --failure-level=WARN doc.adoc
The processor will convert the entire document, but the application will complete with a non-zero exit status.
When using the API, you can consult the logger for the max severity of all messages reported or look for specific messages in the stack.
It's up to the application code to decide how and when to terminate the application.
[#undefined]
== Undefined attribute
The `attribute-undefined` attribute controls how expressions that undefine an attribute are handled.
By default, the line is dropped since the expression is a statement, not content.
This attribute has two possible values:
`drop`:: substitute the expression with an empty string after processing it
`drop-line`:: drop the line that contains this expression (default setting; matches behavior of AsciiDoc.py)
The option `skip` doesn't make sense here since the statement is not intended to produce content.
Consider the following declaration:
```
{set:name!}
```
Depending on whether `attribute-undefined` is `drop` or `drop-line`, either the statement or the line that contains it will be discarded.
It's reasonable to stick with the compliant behavior, drop-line, in this case.
TIP: We recommend putting any statement that undefines an attribute on a line by itself.
= Unset Built-in Attributes
Document attributes can be unset in the document header and document body.
== Unset a document attribute in the header
Document attributes can be unset by adding a bang symbol (`!`) directly in front of or after the attribute's name.
Like when setting an attribute in a document header, the attribute entry must be on its own line.
Don't add a value to the entry.
[source]
----
= Title
:name!: <.>
:!name: <.>
----
<.> An attribute is unset when a `!` is appended to its name.
<.> An attribute is unset when a `!` is prefixed to its name.
Let's unset the attribute `example-caption`.
This is an attribute that is set and assigned a default value of `Example` automatically by Asciidoctor when you use an example block.
[source]
----
= Title
:!example-caption: <.>
----
<.> Example blocks won't be labeled and numbered, e.g., Example 1, because the attribute controlling that behavior is unset with the leading `!`.
== Unset a document attribute in the body
Some document attributes can be turned off in the body of the document using an attribute entry and the bang symbol (`!`) as described in the above section.
For example, if you set the section numbering attribute in the header of your document, but didn't want the two sections midway through the document to be numbered.
To do that, you'd unset `sectnums` before the first section you didn't want numbered and then reset it when you wanted numbering to start again.
[source]
----
= Title
:sectnums: <.>
== Section Title
:!sectnums: <.>
== Section Title
=== Section Title
:sectnums: <.>
== Section Title
----
<.> The `sectnums` attribute is set in the header to activate section numbering throughout the document.
<.> `sectnums` is unset by adding a `!` to it's name.
The `!` can be placed either before or after the attribute's name.
The attribute entry must be placed on its own line.
All of the sections below where the attribute is unset will not be numbered.
<.> `sectnums` is set and all subsequent sections will be numbered.
= Wrap Attribute Entry Values
== Soft wrap attribute values
When a document attribute value is long, it's possible to split it across multiple lines.
Let's assume we are working with a very long attribute.
You can split the value over multiple lines to make it more readable by inserting a space followed by a backslash (`\`) at the end of each continuing line.
[source]
----
:long-value: If you have a very long line of text \
that you need to substitute regularly in a document, \
you may find it easier to split it neatly in the header \
so it remains readable to folks reading your docs code.
----
The backslash and newline that follows will be removed from the attribute value when the attribute is parsed.
The space before the backslash is preserved, so you have to use this technique at a natural break point in the content.
[#hard]
== Hard wrap attribute values
You can force an attribute value to hard wrap by adding a plus (`+`) surrounded by spaces before a backslash.
.An attribute value with hard line breaks
[source]
----
:haiku: Write your docs in text, + \
AsciiDoc makes it easy, + \
Now get back to work!
----
This syntax ensures that the newlines are preserved in the output as hard line breaks.
[[attr-ref-def]]Attribute reference:: An attribute reference marks the location where the information stored in the value of an attribute should be inserted when the document is converted.
This is called _referencing an attribute_.
User-defined attributes are most often referenced, though some built-in attributes that store replacement text or data, such as `author` and `localyear`, can also be used in the document.
See xref:document.adoc#ref-anatomy[Attribute Reference Anatomy] for more information.
Attribute value:: An attribute value is the built-in or user-defined replacement content or behavior that is assigned to an attribute.
Once assigned to an attribute, a value is applied to a document, either as a whole or wherever the attribute is referenced.
The value may be empty, an integer, or a string of characters.
Most built-in attributes have a restricted range of allowable values while user-defined attributes only accept strings.
See the built-in xref:ref-environment.adoc[environment attributes] and xref:ref-document.adoc[document attributes] reference tables for more information.
Also see <<default-def,default attribute value>>.
[[built-in-def]]Built-in attribute:: Built-in attributes are predefined and their names reserved.
Asciidoctor automatically sets many built-in attributes and assigns default values when it processes a document.
However, these built-in attributes can be unset and/or their default values overridden.
See xref:document.adoc#set-built-in[Set built-in document attributes] and xref:element.adoc#attribute-lists[Attribute lists] for more information about using built-in attributes.
Character replacement attribute:: Character replacement attributes are built-in document attributes that can be used when you don't want a character, such as a caret (^) or vertical bar (|), to be interpreted as AsciiDoc syntax.
The xref:ref-character-replacement.adoc[Character Replacement Attributes Reference] lists these built-in attributes and their values.
[[default-def]]Default attribute value:: Many built-in attributes have a default value.
This default value is a built-in value that is used when the attribute is set and its value is left empty.
Set:: When an attribute is _set_ it's "`turned on`".
Attributes need to be set in order for their value to be applied to a document or element.
How an attribute is set depends on what type of attribute it is and where it is being set.
See xref:document.adoc#set-built-in[Set built-in document attributes], xref:document.adoc#set-built-in[Set user-defined document attributes], and xref:element.adoc#attribute-lists[Attribute lists] for more information about setting attributes.
Unset:: When an attribute is _unset_ it's "`turned off`".
When unset, an attribute's behavior or value will not be applied to a document or element.
Only attributes that are automatically set when the document is loaded or converted or attributes the user explicitly set have to be unset if the user wants them to be turned off.
See xref:document.adoc#unset[Unset a document attribute] or xref:element.adoc#unset[Unset a named attribute] for more information.
[[user-defined-def]]User-defined attribute:: User-defined attributes are custom attributes that are created, set, and assigned a value by you.
There are some user-defined xref:document.adoc#user-defined-limits[attribute name and value restrictions].
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment