Map

A DITA map is the mechanism for aggregating topic references and defining a context for those references. It contains references to topics, maps, and other resources.

Syntax

The syntax for representing this component varies depending on the authoring format:

Authoring format Syntax and example
XDITA

<map>

<map id="remote-main">
  <topicmeta>
    <navtitle>Remote Lighting Network</navtitle>
  </topicmeta>
  <topicref href="introduction.dita"/>
  <topicref href="alternatives.dita">
    <topicref href="low-power.dita"/>
    <topicref href="high-power.dita"/>
  </topicref>
</map>
HDITA

<nav>

<nav>
  <h1>Remote Lighting Network</h1>
  <ul>
    <li><p><a href="introduction.html">Introduction</a><p></li>
    <li><p><a href="alternatives.html">Alternative lighting setups</a></p>
      <ul>
        <li><p><a href="low-power.html">Low power installation</a></p></li>
        <li><p><a href="high-power.html">High power installation</a></p></li>
      </ul>
    </li>
  </ul>
</nav>
MDITA

A Markdown file with a title and an unordered of titles for topics and their associated file names

# Remote Lighting Network
 - [Introduction](introduction.md)
 - [Alternative lighting setups](alternatives.md)
   - [Low power installation](low-power.md)
   - [High power installation](high-power.md)

Usage information

A map describes the relationships among a set of DITA topics. Nested topics create a hierarchical relationship. The topic that does the nesting is the parent, and the topics that are nested are the children.

The title component can be used to provide a title for the map. In some scenarios the title is purely informational and is present only as an aid to the author. In other scenarios, the title might be useful or even required. In a map referenced by another map, the title might be discarded as topics from the submap are aggregated into a larger publication.

Rendering expectations

When rendering a map, processors might make use of the relationships defined in the map to create a table of contents (TOC), aggregate topics into a PDF document, or create links between topics in the output.

Attributes

The available attributes vary based on the authoring format:

XDITA
The following attributes are available on this element: architectural attributes, localization attributes, universal attributes, and @id.

For this element, the @id attribute is required.

HDITA
The following attributes are available on this element: localization attributes, universal attributes, and @id.
MDITA
There is no attribute support for the MDITA core profile. For the MDITA extended profile, attributes can be specified by using the HDITA representation.

Examples

This section is non-normative.

The section contains examples of how the map component can be used.

Example 1. XDITA example

The following code sample shows a simple XDITA map. It contains key definitions, including one for variable text, as well as topic references that create a hierarchical table of contents (TOC):

<map>
  <topicmeta>
    <navtitle>Planting a winter garden</navtitle>
  </topicmeta>
  <!-- Key definitions for topics -->
  <keydef keys="winter-garden" href="garden/winter-garden.dita"/>
  <keydef keys="crop-types" href="garden/crops/crop-types.dita"/>
  <keydef keys="selecting-plants" href="garden/tasks/selecting-plants.dita"/>
  <!-- Variable text definition -->
  <keydef keys="product-greenhouse">
    <topicmeta>
      <keytext>Acme Greenhouse</keytext>
    </topicmeta>
  </keydef>
  <!-- TOC hierarchy -->
  <topicref keyref="winter-garden">
    <topicref keyref="crop-types"/>
    <topicref keyref="selecting-plants"/>
    <topicref href="garden/tasks/planting-short-season-crops.dita"/>
    <topicref href="garden/tasks/planting-long-season-crops.dita"/>
    <topicref href="garden/tasks/extending-growing-season.dita"/>
    <!-- … -->
  </topicref>
</map>
Example 2. HDITA example

The following code sample shows a simple HDITA map. It contains key definitions, including one for variable text, as well as topic references that create a hierarchical table of contents (TOC):

<nav>
  <h1>Planting a winter garden</h1>
  <!-- Key definitions for topics -->
  <div data-class="keydef" data-keys="winter-garden" href="garden/winter-garden.html"/>
  <div data-class="keydef" data-keys="crop-types" href="garden/crop-types.html"/>
  <div data-class="keydef" data-keys="selecting-plants" href="garden/selecting-plants.html"/>
  <div data-class="keydef" data-keys="plant-short-season" href="garden/plant-short-season.html"/>
  <div data-class="keydef" data-keys="plant-long-season" href="garden/plant-long-season.html"/>
  <div data-class="keydef" data-keys="extending-season" href="garden/extending-season.html"/>
  <!-- Variable text definition -->
  <div data-class="keydef" data-keys="product-greenhouse">
    <span data-class="keytext">Acme Greenhouse</span>
  </div>
  <!-- TOC hierarchy -->
  <ul>
    <li><a data-keyref="winter-garden">Planting a winter garden</a>
      <ul>
        <li><a data-keyref="crop-types">Crops for a winter garden</a></li>
        <li><a data-keyref="selecting-plants">Selecting your winter crops</a></li>
        <li><a data-keyref="plant-short-season">Planting short-season crops</a></li>
        <li><a data-keyref="plant-long-season">Planting long-season crops</a></li>
        <li><a data-keyref="extending-season">Extending the growing season</a></li>
      </ul>
    </li>
  </ul>
</nav>
Example 3. MDITA example

The following code sample shows a simple MDITA map. It contains key definitions, including one for variable text, as well as topic references that create a hierarchical table of contents (TOC):

# Planting a winter garden
  <!-- Key definitions for topics -->
  <div data-class="keydef" data-keys="winter-garden" href="garden/winter-garden.md"/>
  <div data-class="keydef" data-keys="crop-types" href="garden/crop-types.md"/>
  <div data-class="keydef" data-keys="selecting-plants" href="garden/selecting-plants.md"/>
  <div data-class="keydef" data-keys="plant-short-season" href="garden/plant-short-season.md"/>
  <div data-class="keydef" data-keys="plant-long-season" href="garden/plant-long-season.md"/>
  <div data-class="keydef" data-keys="extending-season" href="garden/extending-season.md"/>
  <!-- Variable text definition -->
  <div data-class="keydef" data-keys="product-greenhouse">
    <span data-class="keytext">Acme Greenhouse</span>
  </div>
  <!-- TOC hierarchy -->
 - [Planting a winter garden](winter-garden)
   - [Crops for a winter garden](crop-types)
   - [Selecting your winter crops](selecting-plants)
   - [Planting short-season crops](plant-short-season)
   - [Planting long-season crops](plant-long-season)
   - [Extending the growing season](extending-season)