How are child topics included in a DITA map?

Child topics are included in a DITA map using <topicref> elements, which act as references to the actual DITA topic files. These <topicref> elements define the order, structure, and relationships of topics within a DITA map.

Using child topics in a DITA map involves:

  • Creating Child Topics: First, individual DITA topics are created which contain the content to be included in the publication. These topics are typically standalone XML documents, each addressing a specific subject or topic.
  • Creating a DITA Map: A DITA map is a separate XML document that serves as the container for organizing and arranging the child topics. The DITA map itself adheres to DITA XML syntax and can include its own <title>, metadata, and other elements.
  • Using <topicref> Elements: Within the DITA map, <topicref> elements are used to reference the child topics to include. Each <topicref> element represents a child topic and specifies the topic’s location within the map’s hierarchy.
  • Nesting <topicref> Elements: <topicref> elements can be nested to define the hierarchy of child topics within the map. This nesting creates a structured order for the content. For example, related topics can be grouped under a common parent <topicref>.
  • Specifying Attributes: <topicref> elements can have attributes that provide additional information, such as the title of the referenced topic, conditions for inclusion, or publication-specific attributes.
  • Defining Relationships: In addition to referencing child topics, relationships can be defined between topics within the DITA map. This includes links like “related topics,” “see also,” or “next/previous” topics. These relationships enhance navigation and user experience.
  • Ordering Topics: The order in which <topicref> elements are placed within the DITA map determines the sequence of topics in the publication. Readers will encounter topics in the order defined by the map.


This is a simplified DITA map for a user guide:

<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
    <title>User Guide for Product XYZ</title>
    <topicref href="introduction.dita">
    <topicref href="getting-started.dita">
        <title>Getting Started</title>
    <topicref href="features.dita">
        <title>Product Features</title>
    <topicref href="troubleshooting.dita">

In this example:

  • The DITA map serves as the container for organizing topics related to the user guide.
  • Four child topics are referenced using <topicref> elements, each with its own title.
  • The order of <topicref> elements determines the sequence of topics in the user guide.
  • Readers can navigate through the user guide based on the structure defined in the DITA map.