You can assign an identifier (i.e., unique name) to a block or inline element using 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.
provides an internal link or cross reference anchor for an element
can be used for adding additional styling to a 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 (
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 (
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.
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
The id (
#) shorthand can be used on inline quoted text.
[#free_the_world]*free the world*
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 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.
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:
[[notice]] This paragraph gets a lot of attention.
or use the shorthand ID syntax:
[#notice] 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:
[[bookmark-a]]Inline anchors make arbitrary content referenceable.
or using the shorthand ID 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:
[[anchor-point]]* list item text
Instead, you would put it at the very start of the text of the list item:
* First item * [[step2]]Second item * Third item
For a description list, the anchor must be placed at the start of the term:
[[cpu,CPU]]Central Processing Unit (CPU):: The brain of the computer. [[hard-drive]]Hard drive:: Permanent storage for operating system and/or user files.
Here’s how you can define the ID for 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.
=== [[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
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).
[[tiger-image,Image of a tiger]] .This image represents a Bengal tiger also called the Indian tiger image::tiger.png
Instead of the bracket form, you can use the macro
anchor to achieve the same goal.
anchor:tiger-image[Image of a tiger]