Inline Linking in DITA

You can create inline links in the content of a DITA topic using the xref element. To insert a link in Oxygen XML Editor Author mode, use the actions available in the Link drop-down list from the DITA Toolbar.

Linking Using Keys

To make links easier to manage, you may choose to use keys for linking, rather than creating direct links to topics. By using keys, you avoid creating a direct dependency between topics, which 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. The first piece is a key definition, which assigns a key to a topic so that other topics can link to it. The second piece is a key reference, which is created in an xref element and specifies the key to link to. Thus, 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. Thus, a key reference points to a key definition on a topicref 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.
Note: You can define more than one key on the same topic reference. Topics can link to any of the keys. This allows you to have topics that link to various keys that are linked to the same topic in one map and to other topics in another map.

Adding a Key to a Map

To add a key to a map:

  1. In the DITA Maps Manager, right-click on the topic reference to which you want to add a key and choose Edit Properties. The Edit Reference dialog is shown.
  2. Enter the key value in the Keys field.
  3. Make sure to save the changes to the DITA map before attempting to insert the key reference in your topic.

Creating a Link Using a Key

To create a link using a key:

  1. In Author mode, highlight the text you want to be a link.
  2. Select Key Reference... from the Link drop-down list that is available in the DITA Toolbar. The Insert Key Reference dialog is displayed.
  3. Use the filter field to find the key you want to link to, then select it and click Insert and close. The link is created in your topic.
Parent topic: Linking