How are topics organized in DITA maps?

In DITA, topics are organized within DITA maps to create a structured hierarchy of content. DITA maps are documents that serve as containers for organizing and arranging individual topics. They define the order and relationships of topics, allowing for the creation of a coherent and structured publication.

Topics are organized within a DITA map by means of the DITA map document, topic references, hierarchy and nesting, attributes, links and relationships, and publication structure.

DITA Map Document: A DITA map is a separate XML document that serves as a table of contents or navigation guide for a collection of DITA topics. The DITA map itself adheres to DITA XML syntax.

Topic References: In a DITA map, you don’t typically include the entire content of topics but rather reference them. Each topic is represented by a <topicref> element within the DITA map. The <topicref> element specifies the topic’s location and its place within the hierarchy.

Hierarchy and Nesting: DITA maps allow you to define a hierarchy by nesting <topicref> elements. This nesting represents the order and structure of the topics. Topics can be organized into sections, chapters, or any other meaningful divisions, depending on the publication’s requirements.

Attributes: <topicref> elements can have attributes that provide additional information, such as specifying the title of the referenced topic, controlling how topics are displayed in the output, or applying conditional processing.

Links and Relationships: DITA maps also enable you to establish relationships between topics. You can create links between topics or set up relationships like “related topics,” “see also,” or “next/previous” topics. These relationships enhance the navigation and user experience of the published content.

Publication Structure: DITA maps are used to define the overall structure of a publication. They determine how the topics are ordered, what topics are included, and how topics are related to each other. This allows you to create different types of publications, such as user guides, manuals, online help systems, and more, by reusing the same topics in different map configurations.

Example: This example shows a simplified DITA map:

<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
    <title>Sample User Guide</title>

    <!-- Chapter 1: Introduction -->
    <topicref href="introduction.dita">

    <!-- Chapter 2: Getting Started -->
    <topicref href="getting-started.dita">
        <title>Getting Started</title>

    <!-- Chapter 3: Advanced Features -->
    <topicref href="advanced-features.dita">
        <title>Advanced Features</title>

        <!-- Nested Topics -->
        <topicref href="feature-1.dita">
            <title>Feature 1</title>
        <topicref href="feature-2.dita">
            <title>Feature 2</title>

    <!-- Appendix -->
    <topicref href="appendix.dita">

In this example:

  • The <map> element is the root element of the DITA map.
  • Each <topicref> element references a DITA topic file, such as “introduction.dita” or “getting-started.dita.”
  • <title> elements define the titles of chapters or topics.
  • The hierarchy is established by nesting <topicref> elements, representing the organization of content.