Search results

DITA: Relationship tables

You can manage links to each topic through a relationship table. Based on the way you arrange topics in a relationship table, you end up with a list of related links at the end of each topic.

A relationship table is an actual table grid that defines the way topics link to each other. You add links to topics in the table's rows and columns. Topics in the same row link to each other. When you output your help, if some of the topics aren't included in the output, they are intelligently not included in the relationship table, so your links don't break.

There are quite a few options for how you can define the linking relationships, but here's the easiest way to implement relationship tables.

Wait until the end to create the links

First, wait until you're mostly done with your help content before you start creating link relationships. You may be changing link names as you write and organize files, and it doesn't make sense to try to establish linking relationships to content that is still in constant flux.

Link related topics through your topicheads directly

In your map file, for each topichead area (which groups topics together), add the collection-type attribute with a value of family, like this:
<topichead navtitle="Links" collection-type="family">
 <topicref href="keyref_links.dita"/>
 <topicref href="inline_links.dita"/>
 <topicref href="related_links.dita"/>
 <topicref href="relationship_tables.dita"/>

All of the topics in this group will link to each other via related links at the bottom (just like with relationship tables). You don't have to actually create a relationship table at all with this method. In almost all cases, you want to link these groups of files to each other.

Linking topics that appear in different groups

For topics that should link across groups, you need to create a relationship table grid in your map file and establish which topics you want linked to each other. Here's the key thing to remember with relationship tables:
  • Topics in the same row link to each other.
  • Topics in the same cell do not link to each other.

Here's an example:

   <relcolspec type="concept">
   <relcolspec type="task">
   <relcolspec type="reference">

          <topicref href="sample_concept.dita"/>

          <topicref href="task_example1.dita"/>
          <topicref href="task_example2.dita"/>

          <topicref href="referencefile.dita"/>

It may make more sense to actually show the table in its display form:

Concept Task Reference




In this relationship table, sample_concept.dita will have links to task_example1.dita, task_example2.dita, and referencefile.dita because they're in the same row.

However, task_example1.dita and task_example2.dita will not have links to each other because they're in the same cell.

If you want topics in the same cell to link to each other, add the attribute collection-type="family" to the relcell element that contains the topics you want to link to each other.

Linking to external resources

Now let's say some topics link to some external files on the web. For example, suppose you want the inline_links.dita topic to link to a topic called You could manage these external resource links in the relationship table, but it's easier to manage them in a related links section of the topic itself. The related links will be combined with the relationship table links at runtime.

To add the related-links element in a topic, add it after the conbody, taskbody, or refbody element:
  <link href=""></link>

This kind of link is useful as a list of relevant resources about the topic. You don't need to manage these links in the relationship table because, as a web resource, you don't need to worry about the topic not being available in the output.

Column headers

If you want the links to be grouped into different related link sections, such as "Related concepts," "Related tasks," and "Related information," add a type attribute to the relcolspec element, like this:

<relcolspec type="concept"/>
<relcolspec type="task"/>
<relcolspec type="reference"/> 

However, I don't think it's wise to separate related links into these different topic types, since many times readers don't clearly distinguish topic types frome ach other, and sometimes concepts are somewhat task-like anyway. If your concepts have lite list formatting in them (using the ol element), the distinction between tasks and concepts may be more fuzzy.

In fact, if you remove the column names, there isn't much reason to separate out the topics into separate columns. You could instead just group all the topics you want to relate to each other in the same cell and add collection-type="family" for that cell.

Working with relationship tables

Probably the easiest way to work with relationship tables in Oxygen is to insert the relationship table code into the bottom of your map file in the Text view (or make sure your cursor is in a valid place in the map file and click the Insert Relationship Table button in the Author view). Then switch to the Author view.

Right-click the map file header tab and select Open in DITA Maps Manager View. Drag the topics from the maps manager view into the cells you want. Remember, if you've already added collection-type="family" to the groups in your map, then you only need to relate those topics that fall outside of the existing groups.

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.