Can you create subsections within a DITA map to group related content?

In a DITA map, subsections can be created to group related content by using <topicref> elements and nesting them within a parent <topicref>. Subsections allow for a structured and hierarchical organization of topics within the map.

Subsections in a DITA Map

Subsections in a DITA map are achieved through the use of nested <topicref> elements. These nested elements create a hierarchy in which topics become subtopics or sections within the map. Here’s an explanation of how this concept works:

Parent <topicref>

The parent <topicref> element represents a higher-level topic or section within the map. It serves as the container for the subsections.

Nested <topicref> Elements

To create subsections, additional <topicref> elements can be nested within the parent <topicref>. These nested elements can reference other topics, and they become subtopics or sections within the map.

This hierarchy allows for the structured organization of related content, making it easier to navigate and understand the document’s structure.


An organization creates subsections within a DITA map for their user guide:

<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
  <title>User Guide</title>
  <topicref href="introduction.dita" />
  <topicref href="installation.dita" />
  <topicref href="operation.dita">
    <topicref href="operation-basics.dita" />
    <topicref href="operation-advanced.dita" />
  <topicref href="troubleshooting.dita" />

In this example:

  • The <map> element defines a DITA map titled “User Guide.”
  • The top-level <topicref> elements reference individual DITA topics, such as “introduction.dita” and “troubleshooting.dita.”
  • The “operation.dita” topic serves as a parent topic within the map. It contains nested <topicref> elements referencing subtopics, which could be operation basics and advanced operation topics. This creates a subsection within the map, where operation-related content is grouped together.
  • By nesting these elements, a hierarchical structure is created within the map, making it clear that the operation section contains subtopics with additional details. This approach enhances the organization and navigation of related content in the DITA documentation.