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 two 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 (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” elements – xref and keyref – you get “insert link here” behavior from DITA-aware systems. By using the “insert content here” elements – conref and conkeyref – you get “insert content here” behavior, which is the better solution when your goal is to insert content.