Home
Cross-referencing
Cross-references are a means of binding individual topics into a coherent and navigable document.
Links in related-links sections
When a topic requires cross-references to other topics where those cross-references will always be valid in the context of the topic, they should be contained within a related-links section after the topic body. In all other cases, cross-references should be defined in the relationship table of the ditamap.

Introduction
Information types and topics
Topics are the building blocks of modular documents, and organising topics by semantic information types is one of the architectural features of DITA.
DITA map files
Syntax and mark-up
Language and punctuation
Graphics and figures
Cross-referencing
Cross-references are a means of binding individual topics into a coherent and navigable document.
- Types of cross-references
  A cross-reference is used in DITA to link or associate one piece of content with another. The cross-reference (xref) element is the primary mechanism for cross-referencing, but other elements also have cross-referencing functions.
- The xref element
  The cross-reference element is used for linking or otherwise cross-referencing text within a topic to other topics, elements within a topic, or resources external to the DITA collection.
- Avoiding in-text cross-references to topics
  Cross-references to other topics should be stored in the relationship table of the ditamap, external to the topic, and not in-line within the text of the topic.
- Cross-referencing topics and external resources
  Cross-references are commonly made to other DITA topics in a collection, and to information resources outside the collection. These external targets can be any type of electronic resource that can be addressed through a URI, including e-mail addresses, documents on a network file server, and Web content.
- Cross-referencing elements in a topic
  Cross-references to elements within topics such as figures and tables allow a reader to easily navigate through a document, whether it is in a page layout format or a hypertext format. The xref element is always used for cross-referencing elements within a topic.
- Links in related-links sections
  When a topic requires cross-references to other topics where those cross-references will always be valid in the context of the topic, they should be contained within a related-links section after the topic body. In all other cases, cross-references should be defined in the relationship table of the ditamap.
  - Structure of the related-links section
    The related-links section of a topic contains link elements which can optionally be grouped into linklist and linkpool container elements. The structure of those elements influences how the links are displayed in the output, and how metadata attributes for the links are managed.
  - The desc element in links
    Descriptive metadata can be added to link elements in the related-links section.
  - The importance attribute and related links
    Setting the importance attribute of a link element in the related-links section in a task topic to required will result in the link appearing in the pre-requisites section of the topic.
  - The linkinfo element
    The linkinfo element can be used to add a block of descriptive text to a link list.
- Managing cross-references
- Cross-references in titles
  You should not use cross-reference elements within topic titles.
Content re-use
Metadata, conditional processing, and indexing
The DITA documentation process
DITA authoring concepts
Moving from style-based authoring to a structured authoring methodology such as DITA requires a radically different approach to writing.

Links in related-links sections

When a topic requires cross-references to other topics where those cross-references will always be valid in the context of the topic, they should be contained within a related-links section after the topic body. In all other cases, cross-references should be defined in the relationship table of the ditamap.

There are three methods through which links can be included in DITA content:

inserting xref elements at any point within the body of a topic
inserting links in a related-links section within a topic, outside the body of the topic
defining link relationships between topics through relationship tables in the ditamap

The most effective method for most documents is the relationship table approach. However, if the cross-references will always be appropriate for the topic, regardless of the context in which it is used, then the related-links section can be used.

The related-links section is technically metadata, and is structured within the topic but outside the body section. It is made up of link elements, which are similar in function to an xref element.