Cross-references in titles

You should not use cross-reference elements within topic titles.

The title element cannot directly contain an xref element, primarily because titles are used in many different presentational contexts, some of which do not support child elements. For example, the title element of a DITA topic may become the title element in the head section of an output XHTML file, which must be plain text. Likewise, the title element of a DITA topic may be used as the basis for link text in its parent topic.

Including child elements in titles therefore reduces the opportunities for re-use, increases the risk of a transformation error caused by mis-interpretation of the mark-up, and complicates what should be a simple semantic element.

However, it is technically possible to embed xref or other child elements within a title element by nesting them within an (allowed) ph element. While the title element cannot contain xref elements, it can contain ph elements, and ph elements can contain xref elements.

Tip: Carefully weigh up the implications before using this workaround.