DITA: Map file (table of contents)
Creating a TOC
topicrefelements in each other, like this:
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:
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.
chunkattribute and specify whether each child topic should appear in the TOC:
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.)
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
Now concept.dita, notes.dita, and conref.dita will all have the attribute
audience="field_engineers". These topics will appear inside a folder
topicgroupelement to do the same bulk-applying of attributes. The difference between
topicheadapplies a hierarchy in the TOC, while
topicgroupdoes not result in any hierarchy.
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
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
Notice that I used
mapref here instead of
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
About 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.