Working with Content References

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 want to expand referenced content on demand (rather than having it be automatically expanded), open the Preferences dialog box (Options > Preferences), go to Editor > Edit modes > Author, and deselect the Display referenced content option.