The @href attribute

The @href attribute specifies the URI of the resource that is addressed. The referenced resource can be another DITA topic or map, an element inside a DITA topic or map, or a non-DITA resource.

The value of the @href attribute MUST be a valid URI reference [RFC 3986]. If the value of the @href attribute is not a valid URI reference, an implementation MAY generate an error message. It MAY also recover from this error condition by attempting to convert the value to a valid URI reference.

The value of the @href attribute can optionally contain a fragment identifier.

When an @href attribute references a DITA resource using a URI without a fragment identifier, the URI resolves to the root element in the referenced document. For the purposes of rendering, such as when a topic reference to a DITA document is used to render the content as HTML, this means that all topics in the target document are included in the reference. For the purpose of linking, the reference resolves to the first topic in the document.

When an @href attribute references a DITA resource using a URI with a fragment identifier, the portion after the hash must be a DITA local identifier. A DITA local identifier takes the following forms:

Target Syntax
Topic element topicID
Element in a topic topicID/elementID
Element in a map mapElementID

Where:

  • topicID is the value of the @id attribute of the DITA topic. If the topic referenced by a DITA local identifier is the same topic that includes the reference, then topicID can be replaced by a period.
  • elementID is the value of the @id attribute of the non-topic element within a DITA topic.
  • mapElementID is the value of the @id attribute of the element within a DITA map document.

See Processing xrefs and conrefs within a conref for more information on how this syntax relates to conref resolution.

Example: Common syntax for the @href attribute

This section is non-normative.

The 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="file.dita#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:

  • topicid is the value of the @id attribute on the referenced DITA topic.
  • elementid is the value of the @id attribute on the referenced (non-topic) DITA element.
  • map-branch is the value of the @id attribute on the referenced DITA map element.