Tutorials
Table of Contents
Tutorials
Structuring Maps for Publish
Structuring Maps Published for Publish

Structuring Maps

Learn how to structure a DITA map for multiple outputs.
section
In DITA, you can structure your maps various ways to create hierarchy, or structure them without any hierarchy at all. The structure you choose to use closely relates to the navigation in your output. This guide looks at three ways to structure your map (flat, topic-hierarchy, and map-hierarchy), combining methods, and important consideration.

Flat

Flat Maps contain topics that are organized without any hierarchy.
section
Flat maps are straightforward. Topics are added to maps without any hierarchy. Here’s an example of a flat map structure:
< map id="_m_faqs" title="FAQs">  	< topicref href="how_do_i_create_a_topic.dita" />  	< topicref href="how_do_i_create_a_map.dita" />  < /map> 

Topic-Hierarchy

section
A map with a topic-hierarchy contains topics with a parent or child relationship. Hierarchy in the map is created by nesting topics within each other in the map. For example:
< map id="_m_user_guide" title="User Guide">  	 	< topicref href="introduction.dita">  	 		< topicref href="features.dita"/>   	< /topicref>  	< topicref href="safety.dita"/>   	... < /map> 
section

Important Considerations

When you create a map with topic-hierarchy, their is a parent-child relationship between some topics. Topics that are child topics are automatically linked to their parent topics. For example, by default when publishing to WordPress, child topics will display on the same page as the parent topic.
It’s also harder to reuse topic-hierarchies than map-hierarchies because map-hierarchies can be easily added to new maps, while topic-hierarchies have to be rebuilt each time.

Map-Hierarchy

section
A map with a map-hierarchy is created by nesting maps within each other. For example:
< map id="_m_user_guide" title="User Guide">   	 	< mapref href="_m_topic_editor.ditamap" />  	< mapref href="_m_map_editor.ditamap" />  < /map> 
section

Important Considerations

Map titles do not display as headings. When published, there is no visual hierarchy created to distinguish between map levels so it looks complete flat. To resolve this, you can add navigational headings for each map title. For more information, see Navigational Headings .
Learn how to create navigational headings for maps.
section
The DITA Open Toolkit does not build its navigation on map titles, you’ll need to insert navigational elements in your DITA map for map titles to display in your output.
Let’s look at an example of a map structured in easyDITA:

In this example, the Master Map (outlined in black) contains a hierarchy of submaps (outlined in blue and green). Publishing the Master Map generates the following navigation in PDF and WordPress:
As you can see, the topic titles (Topic A, Topic B, Topic C, etc) display but the map titles (Getting Started, Interface, Features, Controls) do not. In order to display map titles, you’ll need to define navigational heading elements in the map.
section

Example

Let’s look at an example of a map with hierarchy created from with various levels of submaps:
  • User Guide (master-map)
    • Topic Editor
      • Interface
      • Using the Topic Editor
    • Map Editor
      • Interface
      • Using the Map Editor
When creating navigational headings, you’ll use the following elements for each map:
  • < topichead>
  • < topicmeta>
  • < navtitle>
It’ll look like this:
Here’s an example of the source code for a map with navigational headings for each submap:
< map id="_m_user_guide" title="User Guide">  	< title> User Guide< /title>   	< topichead>  		< topicmeta>  			< navtitle> Topic Editor< /navtitle>  		< /topicmeta>  		< mapref href="_m_topic_editor.ditamap" />  	< /topichead>   	< topichead>  		< topicmeta>  			< navtitle> Map Editor< /navtitle>  		< /topicmeta>  		< mapref href="_m_map_editor.ditamap" />  	< /topichead>   < /map>