Search results

DITA: Map file (table of contents)

The map file primarily defines the table of contents for your help content. You can also include relationship tables, key definitions, and resource files in your map files.
The primary purpose of the map file is to arrange your table of contents. The map file looks like this:
 <title>DITA Topic Map</title>

Creating a TOC

You add references to the topics you want in the table of contents like this:
 <topicref href="keyref_links.dita"/>
 <topicref href="inline_links.dita"/>
 <topicref href="related_links.dita"/>
 <topicref href="relationship_tables.dita"/>
To establish parent/child relationships between topics, nest the topicref elements in each other, like this:
 <topicref href="toc_links.dita">
 <topicref href="keyref_links.dita"/>
 <topicref href="inline_links.dita"/>
 <topicref href="related_links.dita"/>
 <topicref href="relationship_tables.dita"/>

Now the toc_inks.dita file (note the lack of the self-closed angle bracket "/>") will be the parent and the 4 links below it will be children. The parent topic will show the four child topics as embedded links along the shortdesc element from each child topic. Essentially the toc_links.dita file is blank and is filled with a preview of the other files nested below it. This is a general best practice for organizing the TOC.

Note that there is another element called a topichead that also allows you to group topics into hierarchical relationships, like this:

<topichead navtitle="Links">
 <topicref href="keyref_links.dita"/>
 <topicref href="inline_links.dita"/>
 <topicref href="related_links.dita"/>
 <topicref href="relationship_tables.dita"/>

However, many people are opposed to using topichead because it creates a containing folder that does nothing except expand its folder contents when a user clicks it. There's a chance that users may think something isn't working, since clicking an option in the menu doesn't create any change in the main viewing window.

Regardless of the usability issue, it's a good idea to present a preview of the folder's contents on the parent topic anyway. This lets the user browse all the topics in the folder with one glance.

Combining topics

If you want to combine topics in each other, use the chunk attribute and specify whether each child topic should appear in the TOC:
 <topicref href="inserting_links.dita" chunk="to-content">
 <topicref href="inline_links.dita" toc="no"/>
 <topicref href="related_links.dita" toc="no"/>
 <topicref href="keyref_links.dita" toc="no"/>

This output will show Inserting Links as the topic title and the three child topics as subheadings within the topic. It will appear as one file. However, note that if you put inserting_links.dita into a relationship table, the related links will appear directly below the first topic rather than after keyref_links.dita. (Some Open Toolkit people want to decouple topics in the relationship table to allow for more granular relationships; however, I think this is a bug that should be fixed.)

Folder structure

All topics that the map file references need to be in either the same directory as the map or in a subdirectory to the map. Don't reference a topic outside of the map's directory (using ../ syntax).

I think it's easiest to leave all dita files loose in the root folder rather than organizing them into subfolders. Reason being, if you decide to reorganize your files, links to subfolder_a/sample.dita will break when you move sample.dita to subfolder_b.

To maintain some sense or order for loosely coupled files, you can begin the file name with the folder name. Alternatively, if you're on a Mac, you can use virtual folders by tagging the files with folder-like names.

For glossary entries, images, or other files clearly of a different format, using subfolders is probably a good idea.

Editing ditamap files

You can more easily arrange the topics in your ditamap file using the DITA Maps Manager feature in Oxygen. This is the panel that appears on the left of the main window. Right-click your ditamap file tab and select Open in DITA Maps Manager.

Through the DITA Maps Manager, you can easily see if a topic is invalid, as it will include a red exclamation mark next to it. Parent-child hierarchies are also formatted with expand/collapse displays. You can see profiling conditions, edit properties, set parent-child hierarchies, and do other things through the Maps Manager.

Applying attributes to groups of elements

Suppose you want to group a set of topics in your map so that all topics in the group inherit the same attributes and properties. By making the topics children of an element, the children inherit the parent's properties.

 <topichead audience="field_engineers" navtitle="Resources">
  <topicref href="concept.dita"/>
  <topicref href="notes.dita"/>
  <topicref href="conref.dita"/>

Now concept.dita, notes.dita, and conref.dita will all have the attribute audience="field_engineers". These topics will appear inside a folder called Resources.

You can also use the topicgroup element to do the same bulk-applying of attributes. The difference between topichead and topicgroup is that topichead applies a hierarchy in the TOC, while topicgroup does not result in any hierarchy.
 <topicref href="toc_links.dita" audience="field_engineers">
  <topicref href="concept.dita"/>
  <topicref href="notes.dita"/>
  <topicref href="conref.dita"/>

In this example, all the topics in this group will have the audience="field_engineers" attribute applied to them. If you want to apply a grouping independent of any hierarchy, use the topicgroup element.

Linking to non-TOC files

You probably want to link a couple of other files from your ditamap: your notes file (where you store all your conrefs), your relationship table, and your glossary. You could combine them all in the same map, but doing so will make the ditamap file long. When you add these non-TOC links, add an attribute of processing-role:"resource only".

  <topicref processing-role="resource-only" href="notes.dita" />
  <mapref processing-role="resource-only" href="keys.ditamap"/>
  <mapref processing-role="resource-only" href="relationship_table.ditamap"/> 

Notice that I used mapref here instead of topicref. If you use topicref and point to a ditamap file, add format="ditamap" in your attributes.

Additionally, if you're linking to a ditamap, use mapref instead of topicref. If you do use topicref, you must remember to add the format="ditamap" attribute.

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.