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).

In order 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 (or simply press Alt+Enter) 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 Element 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.

Other Ways to Reuse Content

An alternate way to reuse content is to use the Oxygen XML Editor 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.