I miss reltables, part 1
October 14, 2025
How to use frontmatter and scripting to map relationships
One of my favorite features of DITA is the reltable (relationship table), which lets you explicitly map relationships between pieces of content.
I'm not currently at a DITA shop, and I've been mulling over how to build some sort of explicit relationship mapping that makes sense for my docs. I've been thinking about it even harder since I did the SEO audit. During my research, I'd read some things that suggested that using obvious relationship mappings might be good to keep LLMs from making stuff up about your product. Or something, it all feels superstitious at this point.
I decided to go ahead give designing my own relationship mapping a try.
core principles
I start every project with some core principles to keep me from going off the rails, and this is what I decided on for my relationship mapping:
- Single source of truth: Each document's metadata lives only in its own frontmatter. I don't repeat the info anywhere else, it must be programmatically referenced from its source of truth.
- Separation of concerns: The relationship mapping must be separate from content.
- DRY: No duplication of titles, descriptions, or metadata -- this duplicates the single source of truth line, but it's that important.
- Scalable: I need to be able to easily maintain this as documentation grows.
From here, I need to think about how I might best implement this in the docs.
think through the relationship mapping structure
First I need to understand what kinds of relationships to capture and describe. This step informs the entire project. I have a lot of thoughts about this and will write more about those in the next post. For now, I just know that I want to capture a lot of different kinds of relationships.
I'm thinking something like: prereqs, next steps, don't confuse this with other thing, and so on.
how to serve the content
I want to use markdown snippets to serve the content on each page. We already use a lot of snippets in the docs because it's a safe and reliable way to do wild and powerful things with pre-processing scripts. AND it doesn't add any complexity to our build process. When given the choice between trying to inject stuff into the docs versus just building a markdown snippet that Fern can reference in when building, I'm going to choose the simple thing every time.
Using snippets means it'll also be easier to review diffs in GitHub, easier to run Vale checks, and I'm sure there's more pros I'm missing.
The con of this approach is that I can't larp as a developer by building a complicated React component that accepts args that I can never remember how to format.
build the script
I need to build the script that will go in our docs CLI that will convert the relationship map content into markdown snippets that we can import into the page they belong in. I've used this method before, when we used to do simple See Also blocks. It worked awesome, I just scrapped it because no one ever clicked the links and I didn't feel like refactoring the script when we moved from Mintlify to Fern.
I feel like things will be different this time because I'm not adding the related content section hoping for clicks, I'm adding this section to help clarify the relationships between our content for both human readers and AI readers. This shift in the purpose makes this a worthy pursuit for me, whether or not it gets any human use.
add the snippets to the pages
I have never had good luck vibecoding stuff that writes directly to our docs MDX files. I went through this exercise with the original See Also script and found it to be such a hassle that I just did it manually. Depending on how I feel when I get there, I may end up trying to script it, we'll see.
Okay, there's my plan. I'll post more about the project over the next few days as I work out the details.