DITA XML URI Addressing Methods - Examples Guide

Understanding URI-based addressing in DITA XML is essential for creating cross-references and content reuse. This guide presents seven key addressing methods with practical examples.

Overview

DITA uses URI references in attributes like @href and @conref to establish relationships between documents and elements. Fragment identifiers (the part after #) are used to address specific elements within DITA documents.

Reference

  1. Basic topic reference: filename.dita#topicId
  2. Element within topic: filename.dita#topicId/elementId
  3. Same-topic element: #./elementId
  4. Another topic in same file: #topicId
  5. Current topic: #.
  6. Map element: filename.ditamap#elementId (requires format="ditamap")
  7. With path: directory/filename.dita#topicId/elementId

All fragment identifiers must reference elements with @id attributes. The slash (/) separator distinguishes the topic ID from the element ID within that topic.

Example 1: Reference to Another Topic in a Different File

Use Case: Linking to a complete topic in another DITA file.

installation.dita 
<topic id="overview">
  <title>System Overview</title>
  <body>
    <p>See <xref href="installation.dita#install_topic"/>.</p>
  </body>
</topic>
 
<topic id="install_topic">
  <title>Installation Instructions</title>
  <body>...</body>
</topic>

Syntax: filename.dita#topicId

Example 2: Reference to a Specific Element Within Another Topic

Use Case: Linking to a particular section, table, or figure in another topic.

reference.dita 
<topic id="usage">
  <title>Using the Application</title>
  <body>
    <p>See <xref href="reference.dita#config_topic/settings_table"/>.</p>
  </body>
</topic>
 
<topic id="config_topic">
  <title>Configuration Reference</title>
  <body>
    <table id="settings_table">
      <title>Configuration Settings</title>
      <tgroup cols="2">
        <thead>...</thead>
        <tbody>...</tbody>
      </tgroup>
    </table>
  </body>
</topic>

Syntax: filename.dita#topicId/elementId

Example 3: Reference to an Element in the Same Topic

Use Case: Creating an internal cross-reference within the same topic using abbreviated syntax.

File: troubleshooting.dita 

<topic id="troubleshoot">
  <title>Troubleshooting Guide</title>
  <body>
    <p>Check the <xref href="#./error_codes"/> section below.</p>

    <section id="error_codes">
      <title>Common Error Codes</title>
      <p>Error 404: Resource not found.</p>
    </section>
  </body>
</topic>

Syntax: #./elementId (the period represents the current topic)

Example 4: Reference to Another Topic in the Same File

Use Case: Linking between multiple topics in a single DITA document.

File: multi_topic.dita 

<dita>
  <topic id="topic_one">
    <title>First Topic</title>
    <body>
      <p>See also <xref href="#topic_two"/>.</p>
    </body>
  </topic>

  <topic id="topic_two">
    <title>Second Topic</title>
    <body>...</body>
  </topic>
</dita>

Syntax: #topicId

Example 5: Reference to the Current Topic (Same-Topic Reference)

Use Case: Referencing the current topic itself, useful in certain linking scenarios.

Source File: task.dita 

<task id="backup_task">
  <title>Creating a Backup</title>
  <taskbody>
    <context>
      <p>Review <xref href="#."/> carefully.</p>
    </context>
    <steps>...</steps>
  </taskbody>
</task>

Syntax: #. (period represents the current topic)

Example 6: Reference to a Map Element

Use Case: Linking to a specific element within a DITA map.

navigation.ditadocumentation.ditamap 
<topic id="nav_help">
  <title>Navigation Help</title>
  <body>
    <p>See the <xref href="documentation.ditamap#admin_section"
       format="ditamap">administration section</xref>.</p>
  </body>
</topic>
 
<map>
  <title>Product Documentation</title>
  <topicref href="intro.dita"/>

  <topicgroup id="admin_section">
    <topicref href="admin/users.dita"/>
    <topicref href="admin/permissions.dita"/>
  </topicgroup>

  <topicref href="troubleshooting.dita"/>
</map>

Syntax: filename.ditamap#elementId (with format="ditamap" attribute)

Example 7: Reference with Subdirectory Path

Use Case: Linking to a topic in a different directory structure.

reference/api.ditatutorials/getting_started.dita 
<topic id="homepage">
  <title>Documentation Home</title>
  <body>
    <p>For tutorials, see
       <xref href="../tutorials/getting_started.dita#tutorial_intro/first_steps"/>.</p>
  </body>
</topic>
 
<topic id="tutorial_intro">
  <title>Getting Started Tutorial</title>
  <body>
    <section id="first_steps">
      <title>First Steps</title>
      <p>Begin by installing the required software.</p>
    </section>
  </body>
</topic>

Syntax: directory/filename.dita#topicId or directory/filename.dita#topicId/elementId