DITA: Conref (content re-use)
First, create a page where you'll store all of these notes and re-usable components. Then use the
conref tag on the elements you want to pull in the re-usable content.
Suppose the file where you store the re-usable component is called notes.dita with a topic id of "topic_123". On this page, you might have something like this:
On the page where you want to re-use the content, use the
conref element like this:
In other words, use the file name#topic_id/element_id.
conrefpulls in a valid element where you're using the conref. This is the one rule with conrefs. You have to match the elements that you're conref'ing. You can't pull an element into your content from somewhere else if that element isn't valid there. For example, you couldn't pull a
stepselement. This is why it's very common to use
phtags when setting up conrefs.
phtags can be inserted practically anywhere.
Conref of table content
In this case, the ID of the table I'm re-using is
Conref ranges: Including ranges of sibling content
Sometimes you need to insert a range of elements. For example, suppose you have several paragraphs or list items. Rather than using multiple conrefs, you can instead use a range. The conref range will grab all items that are siblings.
To insert a range, you need to add an item to the first item and the last item. Here's an example:
And here's the page where you insert the range. This is a table
You just start the
conref and add a
conrefend element that
refers to the last item in the conref range that you want to pull over.
Conkeyref: Conrefs using keyrefs
conkeyref is similar to conref except that instead of referring to files, you refer to keys to include the target content.
There's a paragraph in this topic with an ID of
opener that I want to
I could reuse the paragraph with a conref like this:
However, sometimes when you have multiple outputs, you may want opener to pull from different files depending on the output. For example, you may have an opener for product A that differs from product B. Product A's map may point its argument key to argument_acme.dita, while Product B may point its argument key to argument_beta.dita.
About Tom Johnson
I'm a technical writer / API doc specialist based in the Seattle area. In this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, visual communication, information architecture, writing techniques, plain language, tech comm careers, and more. Check out my API documentation if you're looking for more info about that. If you're a technical writer and want to keep on top of the latest trends in the field, 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.