How do organizations ensure that glossary and definition links remain accurate in DITA outputs?

Conventions for marking glossary terms in DITA XML involve using the <indexterm> element to make these terms linkable references within your documentation. Linking glossary terms to their definitions or explanations is essential for improving document clarity and user experience. Here’s how you can conventionally mark glossary terms for linkable references in DITA:


To mark a glossary term for a linkable reference, you can use the following DITA XML syntax:

<indexterm id="term-id" term="Term Text" primary="true"/>

Explanation of the attributes used in this syntax:

  • id: A unique identifier for the term. This ID helps in linking to the term’s definition.
  • term: The text of the glossary term to be marked as a linkable reference.
  • primary: Set to “true” to indicate that this is the primary term often used in definitions.


Let’s say you have a glossary term “Acme Corporation” that you want to link to its definition. You can conventionally mark it using this DITA XML code:

<indexterm id="acme" term="Acme Corporation" primary="true"/>

By following this convention, you can create linkable references to glossary terms throughout your DITA documentation, ensuring that readers can easily access term definitions and explanations.