Select Page
We recently had a question about the difference between keyrefs and conkeyrefs so we decided to post our answer.

The difference between keyrefs and conkeyrefs might be easier to see if we take a step back to before DITA used keys. Before there was key referencing, the equivalent elements for direct referencing were xref (cross-reference) and conref (content reference). If you wanted to create a link to direct your reader somewhere else, you used xref. If you wanted to reuse content from somewhere else and make it appear inline where you referenced it, you used conref.

While it’s true that xref can also take a piece of text from somewhere else and place it inline, the main differences between xref and conref are:

  • xref is always rendered as a link
  • xref needs the thing it’s linking to have a title element in order to insert that title text inline. Content from title is the only thing that xref can insert on its own (with the possible exception of additional locational information such as “…on page x” or “in chapter y”).

All of this also applies if you’re using keyref instead of xref, and conkeyref instead of conref. By using “insert link here” features – xref and keyref – you get “insert link here” behavior from DITA-aware systems. By using the “insert content here” features – conref and conkeyref – you get “insert content here” behavior, which is the better solution when your goal is to insert content.

A better way to manage technical documents

Mike Rice

Customer Success Manager at Jorsek, LLC, makers of easyDITA
Mike Rice is a user-centered professional with over 20 years of experience in technical communication, and a tested eye for transforming how information is managed. I'm thrilled to be supporting information professionals using easyDITA to help them focus on their content, its meaning, its value, and its connections.
Mike Rice

Latest posts by Mike Rice (see all)

Free 30 Day Trial