What impact do changes to anchor IDs have on existing internal links in DITA content?

November 10, 2023
|By Bryan Tipper

In DITA XML, changes to anchor IDs within existing content can have a significant impact on internal links. Anchor IDs, often used as targets for internal links, are used to establish the connection between different topics and sections of content. When anchor IDs are altered, it can lead to broken internal links, potentially causing confusion and hindering navigation within the content. Therefore, it’s crucial to understand how changes to anchor IDs can affect the coherence and functionality of your DITA documentation.

If you decide to modify or update anchor IDs within DITA content, you must ensure that these changes are reflected in the associated internal links. Failing to do so will result in broken links, rendering the links ineffective. Users who attempt to follow these links may end up on non-existent or incorrect sections of content, leading to a frustrating user experience and potential loss of trust in the documentation.

Example:

Consider the following DITA topic with an internal link that references an anchor with the ID “section-1”:

<!-- DITA topic with an internal link -->
<topic id="topic-1">
  <title>Topic Title</title>
  <body>
    <p>This is the first section of content.</p>
    <!-- Internal link to section-1 anchor -->
    <p><link href="#section-1">Link to Section 1</link></p>
  </body>
</topic>

If you decide to change the anchor ID from “section-1” to “updated-section-1” within the topic, you must also update the internal link accordingly to maintain the integrity of your content:

<!-- Updated DITA topic with the corrected internal link -->
<topic id="topic-1">
  <title>Topic Title</title>
  <body>
    <p>This is the first section of content.</p>
    <!-- Corrected internal link to updated-section-1 anchor -->
    <p><link href="#updated-section-1">Link to Section 1</link></p>
  </body>
</topic>

By making the necessary updates to internal links after altering anchor IDs, you ensure that users can seamlessly navigate the content without encountering broken links or disruptions in their reading experience.