Edit online

The DITA content reference feature lets you insert a piece of source content by referencing it from its source. When you need to update that content, you only need to do it in one place. The source content can be referenced using the DITA @conref or @conkeyref attributes.

There are several strategies for managing content references:

  • Reusable components - With this strategy, you create a new file for each piece of content that you want to reuse and you insert references from the content of the reusable component files. For example, suppose that you have a disclaimer that needs to be included in certain sections of your documentation. You can create a reusable component that contains your disclaimer and reuse it as often as you need to. If the disclaimer ever needed to be updated, you only have to edit it in one file.
  • Single-source content references - You may prefer to keep many pieces of reusable content in one file. For example, you might want to create a single file that contains all the actions that are available in various menus or toolbars for your software application. Then, wherever you need to describe or display an action in your documentation, you can reuse content from that single file by inserting content references. This strategy requires more setup than reusable components, but might make it easier to centrally managing the reused content and it allows for more flexibility in the XML structure of the reusable content.
  • Arbitrary content references - Although it is not recommended, you can create content references among topics without storing the reusable content in components or a single file. This strategy might make it difficult to manage content that is reused and to maintain continuity and accuracy, since you may not have any indication that content you are editing is reused elsewhere.

A reference to the external content is created by adding a @conref or @conkeyref attribute to an element in the local document. The @conref or @conkeyref attribute defines a link to the referenced content, made up of a path to the file and the topic ID within the file. The path may also reference a specific element ID within the topic. Referenced content is not physically copied to the referencing file. However, by default Oxygen XML Author displays it in Author mode as if it is there in the referencing file. If you do not want referenced content displayed, open the Preferences dialog box (Options > Preferences), go to Editor > Edit modes > Author, and deselect the Display referenced content option.

Note: A reference also displays tracked changes and comments that are included in the source fragment. To edit these comments (or accept/reject changes) right-click the comment or tracked change and select Edit Reference.
Tip: To search for references made through a direct content reference, use the Search References action from the contextual menu.

Accessing Referenced Content

When you reference reusable content using a @conref or @conkeyref attribute, the content is grayed out in the document and can only be edited from the source document. To edit the source of the referenced content, click the Edit Content icon at the beginning of the inserted content. This will open the source document where you can edit the referenced content.