Creating a DITA Content Reference

DITA Content Reference

A DITA content reference, or conref, is one of the main content reuse features of DITA. It is a mechanism for re-using the same content in multiple topics (or even in multiple locations within the same topic).

For a conref to be created, the source content must have an id attribute that the conref can reference. Therefore, creating a conref requires that you add an id to the content to be reused before inserting a conref into the topic that reuses the referenced content.

Assigning an ID to the Referenced Content

To add an id to a DITA element in a topic, place the cursor on the element and select Edit Attributes from the contextual menu to open the in-place attribute editor. Enter id as the Name of the attribute and a value of your choice in the Value field. You can also use the Attributes view to enter a value in the id attribute.

Creating a Content Reference

To create a content reference (conref), follow these steps:

1. Make sure the element you want to reference has an id assigned to it.
2. In Author mode, place the cursor at the location where you want the reused content to be inserted.
3. Select the Reuse Content action on the main toolbar (or from the DITA menu or Reuse submenu of the contextual menu). The Reuse Content dialog box is displayed.
4. In the Location field of the Reuse Content dialog box, select the topic that contains the element you want to reference. The elements that you can reference are presented in a table.
5. Select the Target ID of the element (or elements) from which you want to insert the content, and verify the content in the Preview pane. The id value of the element that you select is automatically added to the Reference to (conref) field.
6. Make any other selections you need in the Reuse Content dialog box. If you select multiple elements, the Expand to (conrefend) field is automatically filled with the id value of the last element in your selection.
7. Click Insert or Insert and close to create the content reference.

Using Copy/Paste Actions to Create a Content Reference

Oxygen XML Editor plugin also includes support for creating content references with simple copy/paste actions. The copied content must be an entire DITA XML element with an ID attribute. Also, the location in the document where you paste the element must be valid, although as long as the Smart paste and drag and drop option is enabled in the Schema Aware preferences page, if you try to paste it in an invalid location, Oxygen XML Editor plugin will attempt to place it in a valid location, and may prompt you with one or more choices for where to place it.

To create a content reference (conref) using copy/paste actions, follow these steps:

1. Copy an entire DITA element that has an ID attribute assigned to it.
2. Place the cursor at a location where the copied element will be valid.
3. Select the Paste as Content Reference action from the Paste Special submenu from the contextual menu.

Other Ways to Reuse Content

An alternate way to reuse content is to use the Oxygen XML Editor plugin Create Reusable Component and Insert Reusable Component actions (available in the DITA menu and the Reuse submenu of the contextual menu). They handle the details of creating an id and conref and creates reusable component files, separate from your normal content files. This can help you manage your reusable content more effectively.

You can also insert reusable content using content key references. This may also make reusable content easier to manage, depending on your particular situation and needs.