Content Reference (conref)

The content reference mechanism pulls a content block to another topic.

Sample project: conref.zip

conref.ditamap

The conref.ditamap references two topics. The source.dita topic is only used as a database topic. It is not rendered in the output, because the @processing-role attribute has the value resource-only and it does not appear in the TOC, because the @toc attribute has the value no. The source.dita topic contains a <note> element, that is pulled into the topic target.dita.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
    <title>conref</title>
    <!--
        The first topic is only used as a database topic,
        it is not rendered in the output and does not appear in the TOC
    -->
    <topicref href="source.dita" processing-role="resource-only" toc="no"/>
    <topicref href="target.dita"/>
</map>

source.dita

The source.dita topic is not designed to be published. It only works as a content container for re-usable elements. It has a <note> element with an @id attribute. All elements with an @id attribute can be pulled to other topics.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="conref-source">
    <title>source</title>
    <body>
        <!-- The following <note> element has an ID and therefore can be pulled into another topic. -->
        <note id="charge-before-use">Use the included USB cable to charge your speaker and make sure
            it is fully charged before first use.</note>
    </body>
</topic>

target.dita

The target.dita topic pulls the <note> element from the source.dita topic using the @conref attribute. The attribute contains a path to the element. The @conref attribute in this example has the following pattern:

PATH TO DITA FILE + "#" + ID OF ROOT ELEMENT + "/" + ID OF RE-USED ELEMENT

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="conref-target">
    <title>target</title>
    <body>
        <!-- The content of the <note> element is pulled from the source.dita file. -->
        <note conref="source.dita#conref-source/charge-before-use"/>
    </body>
</topic>