Expand my Community achievements bar.

How to create global keys to be used across organization content?



Step 1: Create a global map for storing your keys.

  1. Create a map and add the keyref element to it.



<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "technicalContent/dtd/map.dtd">
<map id="map.ditamap_ffbdbf06-8658-4311-ad84-1c631bba904f">
  <keydef keys="adobe">
      <linktext>Adobe Systems</linktext>
  <keydef keys="AEM">
      <linktext>Adobe Experience Manager</linktext>



  1. Here we have defined two definitions, as shown above, provided a keyref as “AEM” for the “Adobe Experience Manager” text.

Step 2: Add this global key map to your publication map.

  1. Now add this map to your publication map



<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "technicalContent/dtd/map.dtd">
<map id="map.ditamap_cbf4a96d-e382-4e8c-8830-bcc093fe6638">
  <topicref href="sample-topic-using-the-keys.dita" type="topic">
  <mapref format="ditamap" href="global-keys-map.ditamap" type="map">




Step 3: Use the keys to refer to any of the variables defined in the global key map.

  1. Edit the topic and add the key value using the keyref.
  2. As shown in screenshot, a small window will appear from where keywords can be chosen. This will show when you add the “keyword” element.








<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "technicalContent/dtd/topic.dtd">
<topic id="topic.dita_31b00e61-04b5-4193-af7a-68503e88b087">
    <p>This is a sample topic using the keys defined in the global map</p>
    <p>here i am using the key definition for AEM :<keyword keyref="AEM"></keyword></p>








Topics help categorize Community content and increase your ability to discover relevant content.

3 Replies



@Kiran_Mohan : what are the general use cases where I should use keys or variables in DITA?



Hi @DivrajSingh , 

The most common use case - We should use keys and variables in cases where we have some text (maybe product name, company name, etc. ) that is used in many places and might change in the future. Also if there are topics that use different variable values in the context of some other publication then also it would be helpful.


Kiran Mohan


Level 3

Thanks for this post. Just some remarks:

  • With the mapref element you usually don't need the "format" and "type" attributes.
  • You should use the processing-role attribute and set it to "resource-only" for your key definition map.
<mapref href="global-keys-map.ditamap" processing-role="resource-only" />

Best regards,