ids.adoc 5.58 KB
Newer Older
1
= ID Attribute
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70

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
71
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.
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
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:

117
.Incorrect position for an anchor ID in front of a list item
118
119
120
121
122
123
124
125
126
127
[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]
----
128
129
130
131
132
133
134
135
136
include::example$id.adoc[tag=anchor-list-item]
----

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

.Define an inline anchor on a description list item
[source]
----
include::example$id.adoc[tag=anchor-dlist-item]
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
----

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