ditamap

A ditamap is a DITA map file that defines the structure, scope, and navigation of a DITA-based publication. It is commonly stored with the .ditamap extension and is an XML document that guides how topics are organized and published.

The core concept of a ditamap is to reference topics and submaps in a hierarchical arrangement. Its primary building block is the topicref element, which points to a topic file (or to another map) via attributes such as href. Topicrefs can be nested to form sections and subsections, creating a tree that represents the intended order and grouping of content. A ditamap may also include metadata at the map level and optional attributes such as title or label to describe each reference.

A ditamap serves several publication functions. It defines the structure used to generate outputs such as HTML, PDF, or EPUB, and it influences the generation of navigational components like tables of contents and sidebars. In addition, a ditamap can reference ditavals to apply content filtering for different audiences or output conditions and can participate in content reuse through cross-references to other maps or topics.

In practice, writers and publishers use ditamaps to assemble content from multiple topics into coherent publications, manage complex documentation sets, and tailor outputs for specific products or audiences. Good practices include keeping maps focused and maintainable, avoiding excessive nesting, modularizing topics, and using separate maps for different deliverables or audiences to facilitate updates and versioning.