@href
attributeThe @href
attribute is used to reference another DITA topic or map, a
specific element inside a DITA topic or map, an external Web page, or another non-DITA
resource.
The value of a DITA @href
attribute must be a valid URI reference [RFC 3986]. It
is an error if the value is not a valid URI reference. An implementation MAY generate an error message; it MAY recover from this error condition by
attempting to convert the value to a valid URI reference. Note that the path separator character
in a URI is the forward slash (/
); the backward slash character (\
) is not permitted
unescaped within URIs.
When an @href
attribute references a DITA resource, an @href
value that consists of a URI without a fragment identifier resolves to the document element in
the referenced document. For the purposes of rendering, such as when a
<topicref>
reference to a DITA document is used to render the content as
HTML, this means that all topics (and topic specializations) in the target document are included
in the reference. For the purpose of linking, the reference resolves to the first (or only)
topic (or topic specialization) in the document.
An @href
value that consists of a URI with a fragment identifier must have a
DITA local identifier as the portion after the hash. A DITA local identifier consists of
topicID/elementID
for a subelement of a
topic, and of elementID for topics, maps, and subelements of a map. If the topic referenced by a DITA local identifier is for the same
topic, then topicID can be replaced by a period; see Processing xrefs and conrefs within a conref for more information on how this syntax relates to conref resolution.
Note that certain characters - including but not limited to the hash sign ("#"), question mark
("?"), back slash ("\"), and space - are not permitted unescaped within URIs. Such characters
must be percent-encoded. Also note that the ampersand ("&") and less than (<
)
characters are not permitted in XML attribute values; they must be represented by appropriate
character or entity references. Some tools might perform this encoding automatically, while
other tools might require that users either avoid the special characters or manually insert the
encoding.
@href
attributeThe following table includes some examples of common @href
syntax. Note that
these examples represent only a few common scenarios and are not all inclusive.
Target | Syntax |
---|---|
The first topic in a DITA document | href="file.dita" |
A specific topic in a DITA document | href="file.dita#topicid" |
A non-topic element inside a DITA topic | href="#topicid/elementid" |
A non-topic element inside the same DITA topic as the reference | href="#./elementid" |
An element in a DITA map | href="myMap.ditamap#map-branch" |
An image | href="exampleImage.jpg" |
An external resource | href="http://www.example.org" |
where:
@id
attribute on the DITA
topic.@id
attribute on the
(non-topic) DITA element.@id
attribute on the DITA
map element.