What Is a DITA Map and How Does It Work?

A DITA map is an XML document that organizes individual, modular DITA topics into structured hierarchies to produce cohesive publications like PDFs, online help centers, or user manuals. In the Darwin Information Typing Architecture (DITA), content is written in standalone, reusable chunks rather than long monolithic documents. The DITA map serves as the structural blueprint that sequences, links, and filters these discrete topics, enabling technical writers to publish tailored documentation deliverables from a single source of content.

The Role of a DITA Map

In a topic-based authoring model, topics exist independently and contain no knowledge of where they appear in a final document. A DITA map provides this missing context. Instead of containing raw narrative text, a DITA map contains pointers—known as topic references (<topicref>)—that point to specific XML topic files on a file system or in a component content management system (CCMS).

By decoupling content creation from content organization, DITA maps allow a single XML topic to be reused across multiple manuals, guides, or help portals without duplicating source files.

How a DITA Map Assembles Deliverables

A DITA map transforms loose topics into a unified deliverable through several core mechanisms:

  1. Hierarchy and Navigation Structure The nesting of <topicref> elements inside the map determines the table of contents (TOC) and document hierarchy. For example, placing a topic reference inside another creates a parent-child relationship, turning the child topic into a subsection in a PDF or a sub-page in an HTML output.

  2. Relationship Tables (<reltable>) Hardcoding hyperlinks inside individual topics breaks their reusability across different contexts. DITA maps solve this by using relationship tables. A <reltable> defines non-hierarchical links between related concepts, tasks, and reference topics at the publication level. When the deliverable is generated, the publishing engine automatically inserts the appropriate “Related Links” into the output.

  3. Global and Topic-Level Metadata Metadata applied at the map level cascades down to all referenced topics unless overridden. This ensures consistent indexing, search keywords, copyright information, and categorization across the entire deliverable.

  4. Conditional Filtering and Flagging DITA maps can apply profiling attributes (such as audience="admin", platform="linux", or product="enterprise") to individual topic references or entire branches. Combined with filter files (such as DITAVAL files), technical communicators can generate multiple customized outputs from the same map structure without altering the underlying content.

  5. Map Nesting (Submaps) Large documentation sets can be broken down into smaller, manageable maps using <mapref>. These submaps can represent specific chapters or functional modules and can be embedded within a master deliverable map.

The Output Generation Process

When a deliverable is built, a publishing engine, such as the DITA Open Toolkit (DITA-OT), reads the master DITA map. The engine parses the map, retrieves all referenced XML topic files, resolves the relationship tables, applies conditional filters, and compiles the elements into the desired format, such as PDF, HTML5, WebHelp, or EPUB. The result is a unified, fully cross-referenced document derived entirely from discrete, modular XML sources.