Your achievements

Level 1

0% to

Level 2

Tip /
Sign in

Sign in to Community

to gain points, level up, and earn exciting badges like the new
Bedrock Mission!

Learn more

View all

Sign in to view all badges

Map Keys and Key Reference Links


Level 2

To use a Key Reference link in a topic, you have to manually enter in the keys="" into the map like this: 

<topicref href="GUID-ae29861e-c03c-41b5-a290-71060f0528cd.dita" keys="TestingNotes" type="concept"></topicref>


If you edit the map using the cross-reference menu icon, the keys are defined with a keydef, like this: 

<topicref href="GUID-2dfc8826-1b96-4fc7-9e0c-3b112a1a760a.dita" type="concept">

<keydef keys="TestingNested"></keydef>



Only the first option results in the key appearing in the Key Reference selection drop-down when inserting a xref link into a topic. Why? Why does XML Editor not insert the keys definition into the map correctly so that it'll work? What is the purpose of this menu option relative to the maps?

5 Replies


Level 1

@stitchsds : Which version of AEM Guides / XML Documentation are you using?



@stitchsds :

As I checked currently you have to do following:

- Add a topic ref pointing to any topic

- Then in editor, you have to remove the href, and then from properties panel you have to select an attribute "keyref" where you get the browse option which will open the dialog to choose the key 




The above steps would achieve what you want - but these steps can be avoided by providing an option directly on "Insert Topicref" dialog to be able to add keyref instead of just href. 

I hope this is what you are looking for. Once you confirm we can log a change request for same.


We can log a change request for same once you confirm


Level 2

Yes, a menu option to add the key to the map would be nice. In XMetaL, when editing the map, you select a topic, click Properties within the map editor, and you can add the Key in a field. If you can have a similar option within the map editor for Guides, that would be great.


It looks like most of the menu options when editing a map remain the same as when editing a topic, which implies these options will work when they do not.




I have raised a change request and engineering will pick this up soon.