Tutorials
Table of Contents
Tutorials
Structuring Maps Published to WordPress
Structuring Maps Published to WordPress

Structuring Maps Published to WordPress

Learn how to structure DITA maps so they publish to WordPress correctly.
Publishing to WordPress uses a Table of Contents-based navigation that is built using DITA maps. So, your map structure directly relates to your WordPress site navigation.
You can create a DITA map with various levels of hierarchy and use that map to generate your navigation in WordPress. But because WordPress does not build its navigation on map titles, you’ll need to insert navigational elements in your DITA map for it to display in WordPress.
Note:By default, maps and topics are posted to WordPress as Pages. To change this, contact an easyDITA representative.
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 WordPress:
As you can see, the topic titles display but the map titles do not. In order to display navigational headings for maps, you’ll need to use specific elements in the map structure.
This guide will look at structuring maps so navigational headings display when publishing to WordPress. More specifically, it’ll look at structuring two types of maps: Flat-Master-Map and Multi-Level-Master-Map .

Flat-Master-Map

Flat-master-maps contain topics that are organized without any hierarchy.
When structuring a map for publishing, you can use a flat-master-map to hold your content. Flat-master-maps do not contain any submaps, instead topics are added to a map without any hierarchy.
Let’s look at an example of a flat-master-map structure:
  • FAQs (master-map)
    • How do I create a topic? (topic)
    • How do I create a map? (topic)

Structure

For flat-master-maps, you only need to label the map using the < title> element. Insert the < title> element in the following location:
< map id="_m_faqs">  	< title> FAQs< /title>  	< topicref href="how_do_i_create_a_topic.dita" />  	< topicref href="how_do_i_create_a_map.dita" />  < /map> 

Multi-Level-Master-Map

Multi-level-master-maps contain a hierarchy of maps and require several elements to create navigational headings.
When structuring a map for publishing, you can use a multi-level-master-map to organize your content. A multi-level-master-map contains a hierarchy of submaps.
Let’s look at an example of a multi-level-master-map with various levels of submaps:
  • User Guide (master-map)
    • Topic Editor
      • Interface
      • Using the Topic Editor
    • Map Editor
      • Interface
      • Using the Map Editor

Overview

Multi-level-master-maps can contain any number of submaps. When creating maps, you’ll use the following elements:
  • Use the < title> element inside each map to label it
  • Use the < topichead> , < topicmeta> , and < navtitle> elements to create a navigational heading for each map you’re adding as a mapref
Here’s an example of a master-map structure with two submaps:
< map id="_m_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> 
The User Guide map is labelled using the < title> element. And the Topic Editor and Map Editor submaps are added as maprefs nested in the < topichead> , < topicmeta> , and < navtitle> elements. These nested elements create the navigational heading for the map.

Structuring a map

First, let’s look at structuring a map. Using the User Guide map example, we’ll structure the Interface map:
  • User Guide (master-map)
    • Topic Editor
      • Interface
Whenever you create a map, you need to label it using the < title> element. Insert the < title> element in the following location:
< map id="_m_interface">  	< title> Interface< /title>  	< topicref href="topicA.dita" />  	< topicref href="topicB.dita" />  < /map> 

Adding a map to another map

Now that the map is structured and labeled, you can add it to another map and create an navigational heading for it. Continuing with the example above, you’ll add the Interface map you just created to the Topic Editor map:
  • User Guide (master-map)
    • Topic Editor
      • Interface
First, create the Topic Editor map and label it using the < title> element. For example:
< map id="_m_topic_editor">  	< title> Topic Editor< /title>  < /map> 
Next, create the navigational heading for the Interface map using the < topichead> , < navtitle> , and < topicmeta> elements. Here’s an example of the nesting structure:
< map id="_m_topic_editor">  	< title> Topic Editor< /title>  	< topichead>  		< topicmeta>  			< navtitle> Interface< /navtitle>  		< /topicmeta>  	< /topichead>  < /map> 
Now, add the Interface map as a mapref in the following location:
< map id="_m_topic_editor">  	< title> Topic Editor< /title>  	< topichead>  		< topicmeta>  			< navtitle> Interface< /navtitle>  		< /topicmeta>  		< mapref href="_m_interface.ditamap" />  	< /topichead>  < /map> 

Adding a map to the master-map

You can continue nesting maps within each other to create as many level of maps as you want. When you’re ready to add the highest level submap to the master-map, you can add it using the same nesting structure.
Let’s look at adding the Topic Editor map to the User Guide master-map:
  • User Guide (master-map)
    • Topic Editor
      • Interface
Create the User Guide map and label it using the < title> element. For example:
< map id="_m_user_guide">  	< title> User Guide< /title>  < /map> 
Next, create the navigational heading for the Topic Editor map using the < topichead> , < navtitle> , and < topicmeta> elements. Here’s an example of the nesting structure:
< map id="_m_user_guide">  	< title> User Guide< /title>  	< topichead>  		< topicmeta>  			< navtitle> Topic Editor< /navtitle>  		< /topicmeta>  	< /topichead>  < /map> 
Now, add the Topic Editor map as a mapref in the following location:
< map id="_m_user_guide">  	< title> User Guide< /title>  	< topichead>  		< topicmeta>  			< navtitle> Topic Editor< /navtitle>  		< /topicmeta>  		< mapref href="_m_topic_editor.ditamap" />  	< /topichead>  < /map>