About keyrefs and keydefs

The keyref feature allows you to use indirect addressing in places such as xrefs and related-links.

Instead of referring to a topic directly by its file name, the link is made by means of a symbolic name (keys=”some_name”).

For example, you might make an xref such as the following:

<xref keyref="locale">Import a localized map and its topics</xref>

The link to the target topic is made with the keyref attribute, instead of an href.

The target of this link is established in the map file by inserting the keys attribute into the appropriate topic reference. You can see an example below.

<topicref href="dit1142432953484.xml" keys="locale"/>

Alternatively, you can use a <keydef> element. This allows you, among other things, to make reference to topics outside the scope of the current map, without making them visible in the navigation markup or generating CMS error messages during status changes.

<keydef href="dit1142432953484.xml" keys="locale"/>

Table 1. Keyrefs
Icon	Description
	Unresolved keyref.
	Keyref resolved with an href.
	Keyref resolved with a keyref.
	Keyref resolved with a null link.

keyref best practices

Several ways are available for adding keys to maps; however, you may want to establish a list of variables for use by the entire team rather than have each user define their own. To provide this list of common or corporately-approved variables, the Administrator can configure a list in the Content Store which can be made available for selection in the DITA Map view.