Can you create links to specific sections or elements within a DITA topic?

November 10, 2023
|By Bryan Tipper

In DITA, links can be created to specific sections or elements within a topic. These links allow readers to navigate directly to a particular part of a topic for quick access to relevant information.

Handling these links in DITA involves anchor IDs and using the <xref> element.

Anchor IDs:

To create links to specific sections or elements within a DITA topic, anchor IDs are assigned to those sections or elements.

Anchor IDs are unique identifiers that act as markers for specific content locations within a topic. These IDs can be assigned to headings, paragraphs, tables, or any element to be linked to.

The <xref> Element:

The <xref> element can be used in combination with the keyref attribute to reference these anchor IDs.

The keyref attribute specifies the ID of the target element to link to within the same topic.

DITA processors and authoring tools use this information to generate hyperlinks that take readers to the referenced section or element.

Example:

A DITA topic about a software product requires a link to a specific section within the same topic.

Product_Manual.dita: 


<topic id="product-manual">
  <title>Product Manual</title>
  
  <section id="introduction">
    <title>Introduction</title>
    <p>This is the introduction to our software product.</p>
  </section>

  <section id="installation">
    <title>Installation</title>
    <p>For installation instructions, please see <xref keyref="installation-section"/>.</p>
  </section>

  <section id="usage">
    <title>Usage</title>
    <p>Learn how to use the software in this section.</p>
  </section>
</topic>

In this example:

  • The topic “Product Manual” has three sections: “Introduction,” “Installation,” and “Usage.”
  • To create a link to the “Installation” section, we use the <xref> element with the keyref attribute set to “installation-section.”

Usage in another topic or section:


<p>For details on installing the software, refer to the <xref keyref="product-manual#installation"/> section in the Product Manual.</p>

In this usage, the <xref> element links to the “Installation” section of the “Product Manual” topic using the anchor ID “installation.”