How are links created in DITA XML?

November 10, 2023
|By Bryan Tipper

In DITA, links are used to connect and navigate between topics or resources within a documentation set or on the web. Links are essential for providing cross-references, citations, and easy access to related information. DITA supports several types of links, including internal links, external links, and bi-directional links.

Types of Links in DITA:

Internal Links:

Internal links are used to connect topics or sections within the same documentation set. They enable readers to navigate between related content easily. Internal links are typically represented by the <xref> element.

DITA Markup for Internal Link:

<p>To learn more about this topic, see <xref href="related-topic.dita">Related Topic</xref>.</p>

External Links:

External links are used to reference resources outside of the documentation set, such as websites, external documents, or online references. They are typically represented by the <link> element.

DITA Markup for External Link:

<p>For more information, visit the <link href="https://example.com">Example Website</link>.</p>

Bi-Directional Links:

Bi-directional links are used to create a link that connects two topics or sections to each other. These links are typically used to allow both topics to reference each other. They can be represented by two <xref> elements, one in each topic.

DITA Markup for Bi-Directional Link (In Topic A):

<!-- In Topic A -->
<p>To learn more, see <xref href="topic-b.dita">Topic B</xref>.</p>

DITA Markup for Bi-Directional Link (In Topic B):

<!-- In Topic B -->
<p>For additional details, refer to <xref href="topic-a.dita">Topic A</xref>.</p>

Example:

This example contains two DITA topics, “Installation Guide” and “Configuration Guide,” which require internal links between them to facilitate navigation for users.

Installation Guide (installation-guide.dita):

<topic>
    <title>Installation Guide</title>
    <body>
        <p>This guide provides instructions for installing the software.</p>
        <p>For configuration details, see <xref href="configuration-guide.dita">Configuration Guide</xref>.</p>
    </body>
</topic>

Configuration Guide (configuration-guide.dita):

<topic>
    <title>Configuration Guide</title>
    <body>
        <p>This guide explains how to configure the software after installation.</p>
        <p>For installation instructions, refer to <xref href="installation-guide.dita">Installation Guide</xref>.</p>
    </body>
</topic>

In this example, internal links using the <xref> element are created to connect the “Installation Guide” and “Configuration Guide” topics. Readers can easily navigate between these related topics for a seamless user experience.