Edit online

Working with Keys in DITA

DITA uses keys to insert content that may have different values in particular circumstances. Keys provide a way to reference something indirectly. This can make it easier to manage and to reuse content in a various ways.

You can think of keys as like renting a post office box. Instead of the mail going directly from the sender to your house, it now goes to the post office box. You then go to the post office box and bring the mail back to your house. If you move to a new house, your mail still gets to you because it comes to the same post office box. You do not have to send change of address cards to all the people who send you mail. Your mailbox address is the key that makes sure your mail always reaches you, even if you move.

Similarly, if you use keys in your content to reference other content, you do not have to update the source content to change the value of the key or what it points to. You just change the definition of the key.

Defining Keys in DITA Maps

Keys are defined in maps and can then be reused and referenced throughout the whole structure of the map. It is considered best practice to create a separate submap that contains all of the key definitions and reference that submap in the main (root) map. This makes it easier to manage since they're all in one location.

There are two types of key definitions that can be created in a map:

Using Keys for Values

You can use keys to represent values that may vary depending on the type of output. For instance, you may have several products that share a common feature. When you want to describe that feature, you need a way to insert the name of the product, even though that name is different depending on which product the feature description is being used for. For more information, see Working with Variable Text in DITA.

Assigning Keys to Topics

You can assign a key to a topic and use that key to reference that topic for various purposes, such as reuse or linking. As always, keys are defined in maps, so the key definition is done using the keys attribute of the <topicref> element:

<topicref href="quick-heat.dita" keys="feature.quick-heat"/>

The easiest way to assign keys to a topic (and insert the <topicref> element in its DITA map) is to use the Keys tab in the Edit Properties dialog box. In the DITA Maps Manager, invoke the contextual menu on the topic that will have the key assigned and select Edit Properties. Go to the Keys tab and enter the name of the key in the Define keys field.

Once a key is assigned to a topic, you can use it to reference that topic for various purposes:
  • You can create a link to it using <xref keyref="feature.quick-heat">. This allows you to change the target of the link by changing the topic that is pointed to by the key (for example, by profiling).
  • You can use it in a map to create a reference to a topic by key: <topicref keyref="feature.quick-heat">. This allows you to change which topic is inserted in the map by the build, by changing the topic that is pointed to by the key.
  • You can use it to insert a content reference. In this case, the content reference uses the key to locate the topic to pull content from. It uses a @conkeyref attribute: <procedure conkeyref="feature.quick-heat/preheat-procedure">. In this example, feature.quick-heat is the key, and preheat-procedure is the ID of a procedure within the topic for that key. Using this mechanism, you could have multiple versions of the preheat procedure in various topics and control which one is inserted by changing the topic that is pointed to by the key.

Assigning Keys to Graphics

You can assign a key to an image (using a map to point to the image file) and then insert the image using the key.

Example of a key definition for a targeted image file:
<map id="keydefs">
  <!-- product name -->
  <title>Key Definitions</title>
  <keydef keys="image1" href="../img/image1.png" format="png"/>
</map>