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 has two purposes:

  1. to provide an internal link or cross reference anchor for the element

  2. to reference a style or script used by the output processor

Block assignment

In an attribute list, there are two ways to assign an id attribute to a block element.

  1. Prefixing the name with a hash (#).

  2. Specifying the name with id=<name>.

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

Inline assignment

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

Quoted text block with id assignment using Asciidoctor shorthand
[#free_the_world]*free the world*

Use an ID as an anchor

An anchor (aka ID) can be defined almost anywhere: on a section title or discrete heading (automatic), on a paragraph, on a block or inline image, on listing or literal block, on a phrase, and so forth. The anchor is declared by enclosing a valid ID name in double square brackets or by using the shorthand ID syntax.

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:

Assigning an ID to a paragraph
This paragraph gets a lot of attention.

or use the ID shorthand syntax:

Assigning an ID to a paragraph using shorthand syntax
This paragraph gets a lot of attention.

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:

Defining an inline anchor
[[bookmark-a]]Inline anchors make arbitrary content referenceable.

or using the shorthand ID syntax.

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

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.
[[anchor-point]]* list item text

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

Defining an inline anchor on a list item
* Fist item
* [[step2]]Second item
* Third item

Here’s how you can define the ID for a section using an inline anchor:

Defining the ID of a section using an inline anchor
=== Version 4.9 [[version-4_9]]

To add additional anchors to a section, place them in front of the title.

Adding additional anchors to a section
=== [[current]]Version 4.9 [[version-4_9]]
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.

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.

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.
[[tiger-image,Image of a tiger]]
.This image represents a Bengal tiger also called the Indian tiger

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

Setting an anchor ID using the macro form
anchor:tiger-image[Image of a tiger]