Home
Cross-referencing
Cross-references are a means of binding individual topics into a coherent and navigable document.
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.
Cross-referencing a step
Cross-references to steps are accomplished with the xref element with a type attribute of li.

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.
  - Cross-referencing figures
    Cross-references to figures are accomplished with the xref element with a type attribute of fig.
  - Cross-referencing tables
    Cross-references to tables are accomplished with the xref element with a type attribute of table.
  - Cross-referencing to a page number
    There is no specific mechanism for cross-referencing a page number, because DITA is a source format and page numbers are output-dependent. In page layout outputs, a cross-reference to an element in a topic will be automatically generated as a page reference.
  - Cross-referencing a step
    Cross-references to steps are accomplished with the xref element with a type attribute of li.
  - Cross-referencing a transcluded element
    When re-using content with content references (conref), you must cross-reference to the instance of a conref transclusion, and not to the original source of the conref.
- 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.
- 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.

Cross-referencing a step

Cross-references to steps are accomplished with the xref element with a type attribute of li.

When referring a reader to a step in a task, you should not hard-code the step number. In different contexts (such as when the content is filtered or transcluded) the step number may be different, or if a step is added, there is a high risk that the hard-coded reference won't be updated.

You must always use the xref element to cross-reference steps, with the type attribute set to li. (The li element is the ancestor of the step element.)

You can only reference a step by its id attribute; therefore, before you can cross-reference to a step, you must ensure that the step element's id attribute has a value.

The following example illustrates how to cross-reference a step number. Don't include any text in the xref element, otherwise this text will be rendered (in most publishing tools), not the step number.

<task id="keypad1">
...
<step id="a"> 
      <cmd>..</cmd> 
      </step> 
      <step> 
      <cmd>Repeat step <xref href="#keypad1/a" type="li" /> until the red light displays.</cmd> 
      </step>
...
</task>

Referring to a step in another topic is almost identical; the difference is that the href attribute will include the file name of the other topic. Again, you must set the type attribute to li.

<cmd>Complete step <xref href="c_panel.dita#keypad2/b" type="li" /> of 
the PIN recovery procedure.</cmd>