The map architecture of DITA

Learn about DITA Maps and how you can use them to organize topics for different purposes.

What is a DITA map?

Maps let you organize topics that you want to build into an output web or PDF. You can also generate navigation files based on the map structure, and generate links that get added to the topics.

A map file references one or more DITA topic files using <topicref> elements. The <topicref> elements can be nested to reflect the desired hierarchical relationships of the topics. Map files need to have a file extension of .ditamap to be processed properly.

Maps should only be used to process topics in the same directory as the map, or in subdirectories of the map's directory. While you can still reference topics outside of that scope, you should use the scope attribute (set to peer or external) to let processes know that the targets are out of reach, and should not be processed or copied to the output directory.

The relationships defined in a map can be used to create a Table of Contents (TOC), aggregate topics into a PDF document, or create links between topics in output. Maps provide a way to express these relationships in a single common format that can be used for different outputs. You can identify differences (for example, a topic could be included in the online Table of Contents but not in the aggregated PDF) using a common set of attributes.

Typically a user assistance information component has maps for a task hierarchy, concept hierarchy, and reference hierarchy, plus a relationship table for describing how tasks, concepts, and reference topics relate to each other. It may also include a mixed hierarchy map to support sequential reading. All the maps should be derived from task analysis of user scenarios. You can use maplists to organize your maps, and choose how they get processed.

Parent topic: Frequently Asked Questions about DITA, the Darwin Information Typing Architecture

Why use maps?

Maps separate the context of your information deliverable from its content. In a typical HTML-based web site, any change to the appearance or navigation of the site typically means making updates to dozens or more individual HTML pages. DITA enables all the navigation (sequences, hierarchies, relationtions) to be managed from a DITA map, which allows authors to manage navigation from a single structure, and then generate new web pages as needed.

How does DITA map apply context to topics?

• Organizes topics for different deliverables
  • Different organization for different deliverables — not just different formats for the same content
  • Structured either by a hierarchical sequence or relationship to other topics (or both)
  • Can reuse the same topic with different collections of topics
  • Can apply filters for multiple views on the same topics: by product, by task, …
• Sets properties of the topic at a position within the map
  • Properties include the title and metadata
  • Change the title relative to the parent topic
  • Metadata can identify a topic as advanced for one deliverable and basic for another
    

What does a DITA map example look like?

A small map example

A typical DITA map might look like this: <map title="Tasks">
<topichead navtitle="Installing"
audience="admin">
<topicmeta>
<shortdesc>Install products before
configuring or using them.</shortdesc>
<topicmeta>
<topicref href="installstorage.dita">
<topicref href="unscrewcover.dita"/>
<topicref href="insertdrive.dita"/>
<topicref href="replacecover.dita"/>
</topicref>
<topicref href="installwebserver.dita">
<topicref href="closeprograms.dita"/>
<topicref href="runsetup.dita"/>
<topicref href="restart.dita"/>
</topicref>
<topicref href="installdb.dita">
<topicref href="closeprograms.dita"/>
<topicref href="runsetup.dita"/>
<topicref href="restart.dita"/>
</topicref>
</topichead>
:
</map>

How do maps manage relationships between topics?

• Relationships are specified outside of content for processing and filtering
• Maps support hierarchy, list, and matrix structures for topic references
  • Hierarchy used primarily for navigation structure (table of contents), secondarily for relationships between topics
  • List and matrix used for relationships
• A container within a structure can have a collection type
  • A sequence collection creates parent, prior, and next relationships for the topics
  • A family collection creates interrelationships between the listed topics
  • Relationship table distributes relationships to topics in other cells in the row
• Bidirectional relationships by default, unidirectional when specified