Map keys and IDs play a crucial role in DITA map organization by providing unique identifiers to topics and maps. They enable content reuse, linking, and the establishment of relationships within a DITA project.

Map Keys

Map keys, also known as keys or keyrefs, serve as a means of creating associations between elements in a DITA map and DITA topics. These keys are defined at the map level using the <keydef> element. The key definition consists of a name (e.g., “section-title”) and a reference to a specific topic or map that holds the content to be associated with that key. The purpose of map keys is to enable the reuse and sharing of common content across different topics within a DITA map. Topics reference these map keys using the keyref attribute within their <topicref> elements.

IDs

IDs are unique identifiers assigned to individual DITA topics. Each topic within a DITA project should have a distinct ID. The ID is represented by the “id” attribute in the topic’s XML element. IDs ensure that no two topics have the same identifier within the project. They serve as unique markers for each topic, making it possible to reference and link to specific topics directly. IDs enable authors to establish relationships between topics and, when combined with the keyref attribute, facilitate content reuse and the assembly of structured documentation.

Example

An organization creates a DITA map for their user guide, using keyrefs.

<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
  <title>User Guide</title>
  <keydef keys="section-title" href="topic-section-title.dita" />
  <topicref keyref="section-title" href="introduction.dita" />
  <topicref keyref="section-title" href="installation.dita" />
  <topicref keyref="section-title" href="troubleshooting.dita" />
</map>
    

In this example:

• The <map> element defines a DITA map titled “User Guide.”
• A key definition is established using <keydef> with the name “section-title” and a reference to the topic “topic-section-title.dita.” This key definition can be used to reference a common section title for various topics.
• Multiple <topicref> elements reference topics, and they use the keyref attribute to link to the “section-title” key. This key reference ensures that all these topics share a common section title. By doing so, the order of topics in the map can be easily reorganized without changing the section titles individually.
• The use of IDs in topics would allow for direct linking between topics based on their unique identifiers, creating explicit relationships within the DITA content structure.