Explainer
DITA Maps, Keys, and Conref: How Reuse Actually Works
Maps
The Publication Is a Map
Topics do not know which publication they belong to. A map does: it references topics with topicref elements, nests them to set the hierarchy, and defines the keys they use. The same typed topics can sit in a service manual, a training guide, and a help system, each its own map. A bookmap is the map specialization for traditional books, with front matter, chapters, and appendices.
<map>
<title>Model 3000 Service Manual</title>
<keydef keys="product">
<topicmeta><keywords><keyword>Model 3000</keyword></keywords></topicmeta>
</keydef>
<topicref href="air-filter.dita">
<topicref href="replace-filter.dita"/>
</topicref>
</map>Keys
Name It Once: Keys and Keyref
A key is a name for a resource, bound in a map. Topics refer to the key, not the resource, so the same topic can resolve differently in different maps. The keydef element defines a key without adding anything to the publication's structure. In the map above, the key product holds the product name; a topic uses it like this:
<p>The <keyword keyref="product"/> uses a replaceable air filter.</p>Publish the topic in a Model 4000 manual whose map binds product differently, and the text changes without anyone editing the topic.
Content References
Write It Once: Conref and Conkeyref
A content reference pulls an element's content from somewhere else. It is how approved text (a warning, a legal notice, a standard step) is written once and used everywhere, so a change reaches every use. The address is the file, the topic, and the element:
<!-- warnings.dita holds the approved text once -->
<note id="hot-surface" type="warning">Surfaces are hot after operation.</note>
<!-- any task pulls it in by reference -->
<note conref="warnings.dita#warnings/hot-surface"/>Conkeyref does the same through a key, so which file supplies the content can vary by map. Relationship tables complete the set: tables in the map that define links among topics, so links are managed centrally rather than hard-coded.
Conditions
Vary It: Filtering With DITAVAL
Elements can carry filtering attributes such as @audience, @product, and @platform. At publish time, a DITAVAL profile says which values to include, exclude, or flag. This one removes novice material and anything specific to the Model 2000:
<val>
<prop att="audience" val="novice" action="exclude"/>
<prop att="product" val="model-2000" action="exclude"/>
</val>Together these are the difference between a DITA library and a folder of XML files. They are also where adoption goes wrong most often: reuse by copy, because keys and content references were never set up, recreates exactly the divergence DITA exists to prevent. The DITA Open Toolkit resolves all of it when it publishes. For the aerospace counterpart, S1000D applicability and common information repositories solve the same problems differently.
FAQ
Questions We Hear
What is a DITA map?
A document that organizes topics and other resources into a structured collection: it sets their hierarchy and relationships, and it is the context in which keys are defined and resolved. A map is the publication; the same topics can appear in many maps. A bookmap is the map specialization for traditional books.
What is the difference between conref and keyref?
Conref pulls content from another element into the current one by direct address. Keyref points at a key, a name the map binds to a resource, so what it resolves to can change per map without editing the topic. Conkeyref combines them: a content reference made indirect through a key.
What is a DITAVAL file?
A conditional processing profile: it says which attribute values to include, exclude, or flag when publishing. With it, one source can produce different outputs for different audiences, products, or platforms without copying content.
What is a relationship table in DITA?
A table in a map that defines links among topics by row and column, such as linking each task to its related concepts, so links are managed in one place rather than hard-coded in every topic.
Get In Touch
Making Reuse Actually Work?
We set up keys, content references, and conditions so reuse happens by design, and teach your team to keep it that way.