Home
Cross-referencing
Cross-references are a means of binding individual topics into a coherent and navigable document.
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.
Links to non-DITA resources
Cross-references can be used to link from within DITA topics to non-DITA resources, such as Web URLs, e-mail addresses, and documents stored on file servers. The scope and format attributes of the cross-reference are used to define the nature of the linked resource, and indirectly the way the link will behave.

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.
  - Format of href attribute in cross-references
    The href attribute requires the address of the referenced resource to be in the standard URI format.
  - Links to non-DITA resources
    Cross-references can be used to link from within DITA topics to non-DITA resources, such as Web URLs, e-mail addresses, and documents stored on file servers. The scope and format attributes of the cross-reference are used to define the nature of the linked resource, and indirectly the way the link will behave.
  - Linking in a new window
    The scope attribute of the cross-reference (xref) is used to nominate whether the target topic, file or other resource is external to the DITA source topics. Some publishing tools (such as the DITA Open Toolkit) will generate cross-references with an external scope attribute as hyperlinks that will open the target in a new window.
  - Links to glossary terms
    Special terms used in the body of DITA topics can be linked to their corresponding glossary entry definitions through the keyref feature, introduced in DITA 1.2.
  - Indirect linking with keys
    Indirect linking and referencing is a way of specifying the target of a link or reference in the ditamap, rather than in the topic. The feature was introduced in DITA 1.2. This allows links to have different destinations, depending upon the ditamap in which the topic is used.
- 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.
- 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 to non-DITA resources

Cross-references can be used to link from within DITA topics to non-DITA resources, such as Web URLs, e-mail addresses, and documents stored on file servers. The scope and format attributes of the cross-reference are used to define the nature of the linked resource, and indirectly the way the link will behave.

The four most important attributes in the cross-reference (xref) element are href, type, scope and format.

When linking to non-DITA resources such as PDF files or Web addresses, the scope attribute describes whether the linked resource is treated as part of the DITA collection or external to it. This setting will ultimately determine how the HTML output code will be formed during the publishing process, and then how the browser will handle the link. The format attribute describes the type of resource being linked to.

The main scope attribute values are:

local: the resource forms part of the content collection (and will typically be opened in the current browser when it is output to a hypertext form)
external: the resource is managed separately to the content collection (and will typically be opened in a new browser or tab when it is output to a hypertext form)

Note: The other valid scope attribute of peer is similar to local, but is used when the linked resource is not available at build time. It is only relevant when linking to DITA resources.

The valid format attribute values for non-DITA resources are:

html: the non-DITA file format of the linked resource is HTML or XHTML
pdf: the non-DITA file format of the linked resource is PDF
txt: the non-DITA file format of the linked resource is plain text

file type: the three letter file extension of the non-DITA file format of the linked resource (for example, ppt and odt)

An example of the code for a local and an external cross-reference link is:

<xref href="somefile.html" format="html" scope="local" />
<xref href="somefile.doc" format="doc" scope="external" />
<xref href="http://abc.com/intro.htm" format="html" scope="external" />