ID Attribute

You can assign an identifier (i.e., unique name) to a block or inline element using the id attribute. The id attribute is a named attribute. Its purpose is to identify the element when linking, scripting, or styling. Thus, the identifier can only be used once in a document.

An ID:

  1. provides an internal link or cross reference anchor for an element

  2. can be used for adding additional styling to specific elements (e.g., via a CSS ID selector)

You can assign an ID to blocks using the shorthand hash (#) syntax, longhand (id=) syntax, or the legacy anchor ([[]]) syntax. You can assign an ID to inline elements using the shorthand hash (#) syntax or by adding an anchor adjacent to the inline element using the anchor ([[]]) syntax.

Valid ID characters

AsciiDoc does not restrict the set of characters that can be used for an ID when the ID is defined using the named id attribute. All the language requires in this case is that the value be non-empty. When the ID is defined using the shorthand hash syntax or the anchor syntax, the acceptable characters is more limited (for example, spaces are not permitted). Regardless, it’s not advisable to exploit the ability to use any characters the AsciiDoc syntax allows. The reason to be cautious is because the ID is passed through to the output, and not all output formats afford the same latitude. For example, XML is far more restrictive about which characters are permitted in an ID value.

To ensure portability of your IDs, it’s best to conform to a universal standard. The standard we recommend following is a Name value as defined by the XML specification. At a high level, the first character of a Name must be a letter, colon, or underscore and the optional following characters must be a letter, colon, underscore, hyphen, period, or digit. You should not use any space characters in an ID. Starting the ID with a digit is less likely to be problematic, but still best to avoid. It’s best to use lowercase letters whenever possible as this solves portability problem when using case-insensitive platforms.

When the AsciiDoc processor auto-generates IDs for section titles and discrete headings, it adheres to this standard.

Here are examples of valid IDs (according to the recommendations above):

install
data-structures
error-handling
subject-and-body
unset_an_attribute

Here are examples of invalid IDs:

install the gem
3 blind mice
-about-the-author

Block assignment

You can assign an ID to a block using the shorthand syntax, the longhand syntax, or a legacy block anchor.

In the shorthand syntax, you prefix the name with a hash (#) in the first position attribute.

[#goals]
* Goal 1
* Goal 2

In the longhand syntax, you use a standard named attribute.

[id=goals]
* Goal 1
* Goal 2

In the legacy block anchor syntax, you surround the name with double square brackets:

[[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:

[quote.movie#roads,Dr. Emmett Brown]
____
Roads? Where we're going, we don't need roads.
____
The order of ID and role values in the shorthand syntax does not matter.
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.

Inline assignment

The id (#) shorthand can be used on inline quoted text.

Example 1. Quoted text block with id assignment using shorthand syntax
[#free_the_world]*free the world*

Use an ID as an anchor

An anchor (aka ID) can be defined almost anywhere in the document, including on a 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 shorthand form is the preferred syntax.

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 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.

On block element

To reference a block element, you must assign an ID to that block. You can define an ID using the shorthand syntax:

Example 2. Assign an ID to a paragraph using shorthand syntax
[#notice]
This paragraph gets a lot of attention.

or you can define it using the legacy block anchor syntax:

Example 3. Assign an ID to a paragraph using legacy block anchor syntax
[[notice]]
This paragraph gets a lot of attention.

As an inline anchor

You can also define an anchor anywhere in content that receives normal substitutions (specifically the macros substitution). You can enclose the ID in double square brackets:

Example 4. Define an inline anchor
[[bookmark-a]]Inline anchors make arbitrary content referenceable.

or using the shorthand ID syntax.

Example 5. Define an inline anchor using shorthand syntax
[#bookmark-b]#Inline anchors can be applied to a phrase like this one.#

On a list item

In addition to being able to define anchors on sections and blocks, anchors can be defined inline wherever you can type normal text (anchors are a macros 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:

Example 6. Invalid position for an anchor ID in front of a list item
[[anchor-point]]* list item with invalid anchor

Instead, you would put it at the start of the text of the list item:

Example 7. Define an inline anchor on a list item
* First item
* [[step2]]Second item
* Third item

For a description list, the anchor must be placed at the start of the term:

Example 8. Define an inline anchor on a description list item
[[cpu,CPU]]Central Processing Unit (CPU)::
The brain of the computer.

[[hard-drive]]Hard drive::
Permanent storage for operating system and/or user files.

You can add multiple anchors to a list item or description list term. However, only the first anchor is registered for use as an xref within the document. The remaining anchors are auxiliary and are used for making deep links (i.e., accessible from a URL fragment).

On an inline image

You cannot currently define an ID on an inline image. Instead you need to place an inline anchor adjacent to it.

Example 9. Placing an inline anchor adjacent to an inline image using shorthand
[[tiger-image]]image:tiger.png[Image of a tiger]

Instead of the shorthand form, you can use the macro anchor to achieve the same goal.

Example 10. Placing an inline anchor adjacent to an inline image using a macro
anchor:tiger-image[]image:tiger.png[Image of a tiger]

Add additional anchors to a section

To add additional anchors to a section (with or without an autogenerated ID), place the anchors in front of the title (without any spaces).

Example 11. Add additional anchors to a section using inline anchors
[#version-4_9]
=== [[current]][[latest]]Version 4.9
You cannot use inline anchors in a section title to make internal references to that section. The processor will flag these as possible invalid references. These additional anchors are only intended for making deep links using an alternate ID.

Remember that inline anchors are discovered wherever the macros substitution is applied (e.g., paragraph text). If text content doesn’t belong somewhere, neither does an inline anchor point.

Customize automatic xreftext

It’s possible to customize the text that will be used in the cross reference link (called xreflabel). If not defined, the AsciiDoc processor 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).

Example 12. An anchor ID with a defined xreflabel. The caption will not be used as link text.
[[tiger-image,Image of a tiger]]
.This image represents a Bengal tiger also called the Indian tiger
image::tiger.png[]