Create a key definition

You can define a variable in a map as a key and then insert that key into any number of topics within the map.

Keys are useful for managing content consistency and for efficiency. Use keys to define items such as names for products or features, then edit the key in the map that defines that product or feature name.

The two most typical methods to define and add keys to your content are:

  • Define keys in a map, and then add them to the map's topics
  • Define keys in a submap, then reuse the submap by adding it to other maps with topics that require the keys you defined

You can also have multiple definitions of a key. If you have two maps where the same key defines a name differently, topics with that key automatically update with the correct product or feature name for the related map.

If multiple definitions of a key exist within a map, the first definition takes precedence over any subsequent definitions, unless you set a specific scope for the keys that alters this default.

You must check in a map before any new key definitions go into effect.

To create a key definition:

  1. In Structure view for Map Editor click Edit.
  2. Select the location in the map where you want to add the key, and then click .
  3. In the resulting pop-up menu, select New Element, and then choose Same Level or Sub Level, based on whether you need to create the key as a sibling or child of the item you selected.
  4. In the resulting New Element dialog, click the Element dropdown menu and select <keydef>.
  5. In the Keyname field, enter the name of the key.
  6. For the Value, choose one of the following options:
    • Keyword provides you with an addition to the keys map and requires you to enter a value that you will use as a reference for that key
    • Object Reference supports insertion of a reference to an image, topic, or map resource, but requires you to enter its scope as defined by DITA: local, peer, or external
    • New Topic Reference supports creation of targeted keys, based on the topic conditions you set
    • Web Link provides support for referencing live website links
  7. Click Insert.

The map now contains the <keydef> element with the values you defined.

Once you check in the map, you can insert the key you defined into a topic.