Linking in DITA Topics

Direct Links

You can create in-line links in the content of a DITA topic using the xref element. The destination of the link can be expressed directly by using the href attribute and the target can be another topic or a specific element within the other topic, another location within the same topic, a file, or a web link. You can also create direct related links to topics, files, or websites in a DITA topic using the related-links element.

Indirect Links Using Keys

The destination of the link can also be expressed indirectly by using keys to create either in-line links or related links (with the keyref attribute). By using keys, you avoid creating a direct dependency between topics. This makes links easier to manage and can make it easier to reuse topics in various publications. It can also be helpful in verifying the completeness of a publication, by ensuring that a publication map provides a key definition for every key reference used in the content.

Links based on keys require two pieces:

Key Definition - Assigns a key to a topic so that other topics can link to it. For more information, see Inserting and Defining Keys in DITA Maps.
Key Reference - Created in an xref element and specifies the key to link to.

The key reference points to a key definition, and the key definition points to a topic. Key definitions are created in maps, as an element on the topicref element that points to a topic. This allows you to assign a particular key to one topic in one map and to another topic in another map. When a topic that links to that key is used in each of these maps, the links work correctly in both maps.

Inserting a Link in Oxygen XML Editor

To insert a link in Author mode, use the actions available in the

Link drop-down menu from the toolbar (or the

Link submenu in the contextual menu or DITA menu). You can choose between the following types of in-line links:

Cross Reference

Opens the Cross Reference (xref) dialog box that allows you to insert a link to a target resource at the current location within a document. The target resource can be the location of a file or a key that is already defined in your DITA map structure. Once the target resource has been selected, you can also target specific elements within that resource. Depending on the context where it is invoked, the action inserts one of the following two elements:

xref - Used to link to other topics or another location within the same topic and points to the target using the href attribute.
fragref - A logical reference to a fragment element within a syntax diagram and points to the target using the href attribute.

Figure: The Cross Reference (xref) Dialog Box

This dialog box includes the following sections and fields:

Choose the Target Resource Section

Location - If you select Location for the target, the link is expressed in an href attribute.

Key - If you select Key for the target, keys will be used to express the link in a keyref attribute. You can use the

Choose Key Reference button to open the Choose Key dialog box that allows you to select one from a list of all the keys that are gathered from the root map (you can also select one from the drop-down list in the Key field).

Select the Target Element Section

This section can be used to target a specific element inside the target resource.

Show elements of type: You can use this drop-down list to select specific types of elements to be displayed in the subsequent table. This can help you narrow down the list of possible source elements that you can select.
Text Filter Field: You can also use the text filter field to narrow down the list of possible source elements to be displayed in the subsequent table.
Element Table: Present all the element IDs defined in the source topic. Use this table to select the Element ID of the element that you want to reference.
Preview Pane: Displays the content that will be references.
Source Pane: Displays the XML source code of the element to be referenced.

Once you click Insert or Insert and close, the configured cross reference is inserted into your document.

Tip: You can easily insert multiple cross references by keeping the dialog box opened, using the Insert button.

File Reference

Opens the File Reference dialog box that allows you to insert a link to a target file resource at the current location within a document. The target resource can be the location of a file or a key that is already defined in your DITA map structure. It inserts an xref element with the value of the format attribute set to xml.

Choose the Target Resource: Location - If you select Location for the target file, the link is expressed in an href attribute.; Key - If you select Key for the target file, keys will be used to express the link in a keyref attribute. You can use the Choose Key Reference button to open the Choose Key dialog box that allows you to select one from a list of all the keys that are gathered from the root map and defined as a non-DITA resource (you can also select one from the drop-down list in the Key field).

Web Link

Opens the Web Link dialog box that allows you to insert a link to a target web-related resource at the current location within a document. The target resource can be a URL or a key that is already defined in your DITA map structure. It inserts an xref element with the value of the format attribute set to html, and scope set to external.

Choose the Target Web Resource: URL - If you select URL for the target resource, the link is expressed in an href attribute.; Key - If you select Key for the target resource, keys will be used to express the link in a keyref attribute. You can use the Choose Key Reference button to open the Choose Key dialog box that allows you to select one from a list of all the keys that are gathered from the root map and defined as a non-DITA resource (you can also select one from the drop-down list in the Key field).

Related Link to Topic

Opens the Cross Reference (xref) dialog box that allows you to insert a link to a target resource in a related links section that is typically at the bottom of your topic (although this depends on the behavior of the output transformation). The target resource can be the location of a file or a key that is already defined in your DITA map structure. Once the target resource has been selected, you can also target specific elements within that resource. If a related links section does not already exist, this action creates one. Specifically, it inserts a link element inside a related-links element.

Figure: The Cross Reference (xref) Dialog Box

This dialog box includes the following sections and fields:

Choose the Target Resource Section

Location - If you select Location for the target, the link is expressed in an href attribute.

Key - If you select Key for the target, keys will be used to express the link in a keyref attribute. You can use the

Choose Key Reference button to open the Choose Key dialog box that allows you to select one from a list of all the keys that are gathered from the root map (you can also select one from the drop-down list in the Key field).

Select the Target Element Section

This section can be used to target a specific element inside the target resource.

Show elements of type: You can use this drop-down list to select specific types of elements to be displayed in the subsequent table. This can help you narrow down the list of possible source elements that you can select.
Text Filter Field: You can also use the text filter field to narrow down the list of possible source elements to be displayed in the subsequent table.
Element Table: Present all the element IDs defined in the source topic. Use this table to select the Element ID of the element that you want to reference.
Preview Pane: Displays the content that will be references.
Source Pane: Displays the XML source code of the element to be referenced.

Once you click Insert or Insert and close, the configured cross reference is inserted into your document.

Tip: You can easily insert multiple cross references by keeping the dialog box opened, using the Insert button.

Related Link to File

Opens the File Reference dialog box that allows you to insert a link to a target file resource in a related links section that is typically at the bottom of your topic (although this depends on the behavior of the output transformation). The target resource can be the location of a file or a key that is already defined in your DITA map structure. If a related links section does not already exist, this action creates one. Specifically, it inserts a link element with the format attribute set to xml inside a related-links element.

Choose the Target Resource: Location - If you select Location for the target file, the link is expressed in an href attribute.; Key - If you select Key for the target file, keys will be used to express the link in a keyref attribute. You can use the Choose Key Reference button to open the Choose Key dialog box that allows you to select one from a list of all the keys that are gathered from the root map and defined as a non-DITA resource (you can also select one from the drop-down list in the Key field).

Related Link to Web Page

Opens the Web Link dialog box that allows you to insert a link to a target web-related resource in a related links section that is typically at the bottom of your topic (although this depends on the behavior of the output transformation). The target resource can be a URL or a key that is already defined in your DITA map structure. If a related links section does not already exist, this action creates one. Specifically, it inserts a link element with the attribute format set to html and scope set to external inside a related-links element.

Choose the Target Web Resource: URL - If you select URL for the target resource, the link is expressed in an href attribute.; Key - If you select Key for the target resource, keys will be used to express the link in a keyref attribute. You can use the Choose Key Reference button to open the Choose Key dialog box that allows you to select one from a list of all the keys that are gathered from the root map and defined as a non-DITA resource (you can also select one from the drop-down list in the Key field).