Reusing DITA Content

Reusing Topics in DITA Maps

A DITA topic does not belong to any one publication. You add a DITA topic to a publication by referencing it in a map. You can reference the same topic in multiple maps.

Reusing Content with References and Keys

DITA allows you to reuse content by referencing it in another topic. DITA provides several mechanisms for including content by reference (conref, conkeyref, coderef). A conref (content reference) creates a direct reference to a specific element of another topic. A conkeyref (content key reference) creates a reference to a key, which then points to a specific element in another topic. The advantage of using a conkeyref is that you can change the element that is included by changing the key reference. For example, since keys are defined in maps, if you include a topic in multiple maps, you can use a different key reference in each map. A coderef references an external file that contains literal code.

Oxygen XML Editor Eclipse plugin provides support for all of these mechanisms.

While the conref and conkeyref mechanisms can be used to reference any content element, it is considered best practice to only conref or conkeyref content that is specifically set and managed as reusable content. This practice helps reduce expensive errors, such as an author accidentally deleting the source element that other topics are including by the reference. Oxygen XML Editor Eclipse plugin can help you create a reusable component from your current content.

Reusing Content with Reusable Components

DITA allows you to select content in a topic, create a reusable component from it and reference that component in other locations. Each reusable component is created as a separate file. Anytime the content needs to be edited, you only need to update it in the component file and all the locations in your topics that reference it will also be updated. This can help you to maintain continuity and accuracy throughout your documents.

Reusing Content with Variables

DITA allows you to replace the content of certain elements with a value that is pointed to by a key. This mechanism effectively means that you can create variables in your content, which you can then create multiple outputs by changing the value that the key points to. This is done by profiling the definition of the key value, or by substituting another map with a different key value.

Reusing Content with DITA 1.3 Concepts

DITA 1.3 allows you to use some advanced concepts to expand content reuse possibilities even further. Key Scopes (or scoped keys) allow you to reuse topics with variable content depending on the particular context and it maximizes reuse possibilities for keys. Branch Filtering allows you to reuse the same content that is profiled in multiple ways within the same publication, each time using a different filter.

DITA Reusable Components View

If you use a large amount of keys or reusable components in your DITA project, the DITA Reusable Components view can be quite helpful. It collects all of the keys and reusable components that are defined in the root map and presents them in a dynamic table where you can easily locate and insert references to them.

Reuse Actions in Oxygen XML Editor Eclipse plugin

Oxygen XML Editor Eclipse plugin includes some actions that are specifically designed for DITA reusable content. These actions are available in the contextual menu, the DITA menu, and some are available on the toolbar.

Reuse Content: This action provides a mechanism for reusing content fragments. It opens the Reuse Content dialog box that allows you to insert several types of references to reusable content at the cursor position. The types of references that you can insert using this dialog box include content references (@conref), content key references (@conkeyref), or key references to metadata (@keyref).

Push Current Element

Opens the Push current element dialog box that allows content from a source topic to be inserted into another topic without any special coding in the topic where the content will be re-used.

Edit Content Reference

This action is available for elements with a @conref or @conkeyref attribute. It opens the Edit Content Reference dialog box that allows you to edit the source location (or key) and source element of a content reference (or content key reference), and the reference details (@conref/@conkeyref and @conrefend attributes). For more information, see Reuse Content Dialog Box.

Replace Reference with Content

Replaces the referenced fragment (@conref or @conkeyref) at the cursor position with its content from it source. This action is useful if you want to make changes to the content in the currently edited document without changing the referenced fragment in its source location. If the source content includes references to other topics/resources (hrefs), the operation also resolves those references relative to the new location. Attributes are preserved according to the following priority:

Attributes from the elements in the current document that reference other content are preserved except for attributes with a -dita-use-conref-target value.
Attributes from the referenced content are brought into the replaced elements in the current document except for @id attributes.

Replace All References with Content

Replaces all referenced fragments (@keyref, @conref, or @conkeyref) in the current document with the content. Attributes are preserved according to the following priority:

Attributes from the elements in the current document that reference other content are preserved except for attributes with a -dita-use-conref-target value.
Attributes from the referenced content are brought into the replaced elements in the current document except for @id attributes.

For keyrefs inside <xref> or <link> elements, the @keyref attribute is changed to an @href attribute, while the rest of the content for the keyref is replaced with its source content.

If the source content includes references to other topics/resources (hrefs), the operation also resolves those references relative to the new location.

Remove Content Reference

Removes the content reference (@conref or @conkeyref) inside the element at the cursor position.

Create Reusable Component

Opens a dialog box that helps you to create a reusable component from the current element or selection of elements. If the Replace selection with content reference option is selected in the dialog box, the selection will be replaced with a content reference (@conref). If multiple elements are selected (for example, multiple steps or list items), the selection will be replaced with a content reference range (@conref and @conrefend). For more information, see Creating a Reusable Content Component.

Insert Reusable Component

Inserts a reusable component at cursor location. For more information, see Inserting a Reusable Content Component.

Resources

For more information about reusing strategies in DITA, see the following resources: