The conref attribute

This attribute is used to reference an ID on content that can be reused. It allows reuse of DITA components from phrases to topics, as well as maps and pieces of maps.

Full details on how to resolve the conref attribute can be found in the DITA Architectural specification. This topic primarily includes information on the actual syntax required when using the conref attribute. Note: When using the conref attribute on an element, the content of that element is ignored. For example, if a phrase is marked up like this:

<ph conref="#topic/ph">Something</ph>

the word "Something" will be replaced by the target of the conref.

[edit] Using conref to refer to a topic

The conref attribute may be specified on a topic element to pull in another topic. For example, you could create a series of topics in a composite (ditabase) document or nested context for authoring convenience and then reference each topic individually into a new target location. During output processing, a lookup process will pull the contents of the first topic into the calling topic markup that has the conref attribute.

The conref value follows the same conventions as HTML for normal file links. To refer to target content in a different file, put the full URL of that topic before the # character.

Target elsewhere in the same file:

 conref="#topicid"

First topic in different file:

 conref="filename.xml"

Specific topic in different file:

 conref="filename.xml#topicid"

[edit] Using conref to refer to an element within a topic

The conref attribute also allows you to reuse content within a topic. For example, you could create a <note> in a topic and then reference its ID (using conref) from a <note> in another topic. This allows the content of the note to be used in both locations.

The value of conref is a URI that includes (or consists entirely of) a fragment identifier consisting a number sign ('#') followed by the ID of the topic that contains the element that is the target of the content reference, a slash ("/"), and the ID of the target element. If the URI consists of only a fragment identifier, the target element must be in the same XML document as the reference.

Local target:

 conref="#topicid/elementid"

In different file:

 conref="filename.xml#topicid/elementid"

[edit] Using conref to refer to an element within a map

Within a map, the conref attribute references an equivalent element in the same map or another map. The value of conref is a URI that includes (or consists entirely of) a fragment identifier consisting of the number sign ('#') followed by the ID of the target element. If the URI consists of only a fragment identifier, the target element must be in the same XML document as the reference.

Note that if the conref attribute is used on the map element itself, the attribute may only point to a complete map in another file or resource.

Local target:

 conref="#elementID"

In different file:

 conref="othermap.ditamap#elementID"

[edit] Using the -dita-use-conref-target value

The value -dita-use-conref-target is available on enumerated attributes, and may also be specified manually on other attributes. It indicates that when the element uses conref to pull in content, the attribute with a value of "-dita-use-conref-target" should also be pulled in from the target.

TOC: Language Specification 1.1
Parent topic: Complex attribute definitions
Next topic: The type attribute