📝 Overview
In MadCap Flare, relationship tables allow you to create groups of related topics and define how they link to each other. Unlike regular cross-references, links in relationship tables are dynamic. Because related links are generated at build time from the table, removing a topic from a row (or the project) prevents stale links from appearing after you rebuild.
🎯 Target audience
This guide is intended for technical writers, content developers, and documentation specialists who already use MadCap Flare and want to streamline topic linking with relationship tables.
💡 Key concepts
In a relationship table:
Each row in the table encapsulates a specific subject.
For example, your relationship table includes the content in a specific user guide. One row in the table includes content in the chapter, Getting Started.Topics related to the subject of the row are included in one of three columns, according to the topic type: concept, task, or reference.
For example, you have two concept topics called Workforce Optimization overview and Navigating WFO workspaces, two task topics called Sign in to the portal and Sign out of the portal, and one reference topic called Quick access icons.By default, different topic types in the same row automatically link to one another in your output.
For example, by default, the Workforce Optimization overview topic, the Sign in to the portal topic, and the Quick access icons topics all link to each other.By default, the same topic types in the same row do not link to each other in your output.
For example, by default, the two task topics, Sign in to the portal and Sign out of the portal, do not link to each other.To link the same topic types in the same row to each other, you need to define those topics as a Family. Once you do that, topics in the same Family link to each other in your output.
For example, define the task topics, Sign in to the portal and Sign out of the portal, as a Family. As a result, they link to each other in the output.
This example shows a relationship table for a Getting Started chapter, with concept, task, and reference topics grouped in one row. The accompanying table explains the function of each numbered element.
Relationship table concept
| Seq.# | Summary |
|---|---|
| 1 | Name of the relationship table. |
| 2 | Row in the relationship table. |
| 3 | Concept topics related to the subject of the row. |
| 4 | Tasks topics related to the subject of the row. |
| 5 | Reference topics related to the subject of the row. |
| 6 | By default, different topic types in the same row link to one another in your output. |
| 7 | To link same topic types to each other, define those topics as a Family. |
✅ Before you begin
Ensure you have a working installation of MadCap Flare.
Ensure you have a DITA-structured guide where each topic is one of three types: concept, task, or reference.
Basic familiarity with MadCap Flare is assumed; this guide does not cover introductory concepts.
It’s OK if your guide currently includes a Related topics element. After creating a relationship table, you can replace the existing element entirely or use both—keeping Related topics in some chapters and the relationship table in others.
📌 Steps
To automatically and dynamically link related topics in a guide, create a relationship table. You can edit a relationship table at any time. When working in a project with multiple TOCs, create a new relationship table for each TOC.
The steps include the following:
1. Add Relationship Table
2. Set up your TOC
3. Create Row in the Table
4. Add Topics to the Row
5. Link Same Topic Types to Each Other
6. Final Steps
1. Add Relationship Table
From Project Organizer, add a new relationship table.
From View, select Project Organizer.
From Project, right-click the Advanced folder and select Add Relationship Table.
Add relationship table
On the Add File screen:
Under Source, leave the default New from template.
For File Name, enter a filename for the relationship table.
Select Add.
Add file
The system saves the relationship table in the Advanced folder. On the right pane, you now have an empty relationship table that you can start filling in with your related topics.
Relationship table added
2. Set up your TOC
To easily move the topics from your TOC to your relationship table, move your TOC to appear alongside your relationship table.
By selecting the five lines that appear in the corner of your TOC file, click and drag your TOC.
Click and drag your TOC
When you do that, Flare displays multiple shaded squares, prompting you to place the TOC in a specific location on the screen. For example, to place the TOC on the right side, select the square that is shaded on the right.
Place TOC in shaded square
From your TOC, navigate to the chapter that includes the topics you want to add to the relationship table.
Navigate to chapter in TOC
3. Create Row in the Table
Create the first row in your relationship table.
From the Row Name column in your relationship table, right-click and select Row Properties.
Select Row Properties
In the Row Type field, enter the name of the row (or subject), and click OK.
For example, I want to put links to topics related to getting up and running in an application called Workforce Optimization. Therefore, the name of my row is Getting Started.
Enter row name
The system displays the name of the row in the Row Name column.
Row created
4. Add Topics to the Row
From your TOC, drag and drop the relevant topics to the row in your relationship table.
Review your TOC to determine which topics should be linked in the row.
For example, for my Getting Started row, I want to link the concept topic, Workforce Optimization overview, with the other topics in that chapter. I also want to link the two task topics, Sign in to the portal and Sign out of the portal, to each other.
Drag and drop the topics to the relevant topic type column.
For example:
Drag and drop the concept topics, Workforce Optimization overview and Navigating WFO workspaces, to the concept column.
Drag and drop the task topics, Sign in to the portal and Sign out of the portal, to the task column.
Drag and drop the reference topic, Quick access icons, to the reference column.
Drag and drop topics
5. Link Same Topic Types to Each Other
By default, different topic types in the same row in your relationship table will link to one another. To link topics of the same topic type to each other, define them as a Family.
From the first topic to be included in the Family, right-click and select Cell Properties.
Select Cell Properties
On the Cell Properties screen, from the Collection Type drop-down list, select Family.
Select Family for collection type
Select OK.
The cell you selected is now shaded green, indicating that there is a Family connection between these same topic types. Now, the concept topics, Workforce Optimization overview and Navigating WFO workspaces, will link to one another.
Family connection between topics
Repeat these steps for all topics of the same topic type that you want to link to one another.
6. Final Steps
Add all relevant topics to your relationship table. In addition, add your relationship table snippet to the end of all relevant topics, and update and build your target files. Then, review your output.
Insert the relationship table snippet in every topic included in your relationship table:
From a topic for which you want to add the relationship table snippet, scroll to the bottom of the topic (where your Related topics heading is usually inserted).
Go to Content Explorer.
From the Content folder, go to Resources and Snippets.
From the Snippets folder, drag the snippet, mast_RelTable.flsnp, to the bottom of the topic.
Insert relationship table snippet in topics
If you have existing Related topic elements and links where you are inserting the snippets, remove those elements so they do not appear in the output.
For every target file, from the Relationship Table tab, select the relationship table you created.
This ensures the relationship table links get included in the output.
Select relationship table for targets
Build all relevant targets.
💡 Tips
For large guides, it makes sense to create a relationship table for every chapter in your guide. For smaller guides, up to 50 pages, use a single relationship table.
Every row in a relationship table must have at least two topics. If there are only two topics, they either need to be of different topic types or the same topic type linked together as a Family.
By default, all topics of different topic types in the same row link to each other. Therefore, make sure that all of those topics are actually related to one another. If it does not make sense to link all of them, go granular! Create another row with a more granular subject and link less topics to one another. It is better to have less and more directly related topic links at the end of a topic, than a ton of somewhat or not at all related topic links at the end of a topic.
Do not include chapter page .htm files in a relationship table. Chapter pages typically have their own format with a set Related topics snippet and your output will look messy if you add the relationship table snippet to it as well.
Do not include topics in a relationship table that are part of a workflow. The workflow topic itself has links for each step in the workflow. Including more links on top of that is confusing to the user, and takes away from the specified and directed nature of the workflow.
When linking task topics, your output might result in the same topic link appearing under the Before you begin heading at the beginning of a task, and under the Related topics heading at the end of the same task. Although not ideal, it is okay if this happens. The benefits of using relationship tables outweigh the minor DITA infraction of having the same link twice within the same topic.
✅ Result
View your output. Make sure that the related topics generated by your relationship table are what you expected.
View your output
If the links are not what you expected, open your relationship table, edit it, rebuild your targets, and check again. It’s ok to not get it right the first time! It takes time to understand how to build the relationship tables in a way that results in the right output.
For more information and technical support for MadCap Flare, see Additional resources.