Search results

DITA: Conref (content re-use)

You can re-use notes and other content through an attribute called conref.

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: 

  <topic id="topic_123">
   ...
  <note type="note" id="bolt_warning">Don't overtighten the bolts, as it may cause stripping.</note>

On the page where you want to re-use the content, use the conref element like this:

  <note conref="notes.dita#topic_123/bolt_warning"/>

In other words, use the file name#topic_id/element_id.

Conref of table content

If you're "conrefing" a table element, you have to include all of the table elements, like this: 
   <table conref="notesdita#topic_123/samptable">
    <tgroup cols="2">
     <tbody>
      <row>
       <entry/>
      </row>
     </tbody>
    </tgroup>
   </table>

In this case, the ID of the table I'm re-using is samptable.

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:

<glossdef><p id="ot_first">The open toolkit is what processes your DITA files to transform them into webhelp, pdf, and other outputs.</p>
        <p>There are other processors besides the OT that can achieve similar results.</p>
        <p id="ot_last">OxygenXML does use the Open Toolkit to do its processing, but xMetaL uses another processor.</p>
    </glossdef>

And here's the page where you insert the range. This is a table entry element:

<entry><p conref="glossary/ot.dita#opentoolkit/ot_first" conrefend="glossary/ot.dita#opentoolkit/ot_last"/></entry>

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.

example: 

<keyref keys="argument" href="argument_acme.dita">

There's a paragraph in this topic with an ID of opener that I want to re-use.

I could reuse the paragraph with a conref like this:

<p conref="argument_acme.dita#topicid/opener"/>

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.

To implement the conref using keys, you use conkeyref, like this: 
<p conkeyref="argument/opener"/>

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.

© 2024 Tom Johnson