Titles and headings

Titles are used in a number of mark-up structures in DITA. Titles are a mix of content and metadata. The mark-up in titles should be kept as simple as possible, and workarounds to achieve specific formatting outcomes should not be used.

A title is not the same as a heading. A title is usually considered part of the content (and is typically rendered in the output as a heading), but it also has a role as a metadata container. For example, the title might be used as the basis for link text, outside the context of its topic. In that context, mark-up such as a footnote (fn) or cross-reference (xref) wouldn't make any sense.

A number of mark-up structures in DITA have titles, including:

Avoid using phrase-level mark-up in titles, particularly when the motivation is to achieve a presentational outcome. For example, do not use footnote (fn) elements in titles, as the presentational outcome when a title is displayed in a pop-up window is likely to be unpredictable.

If a title element does not permit a particular type of phrase-level element, do not devise workarounds to force such elements in place.

For example, title does not permit the cite element, but does permit the general phrase (ph) element. That phrase element can itself contain cite. So while the code <title>Such is Life <ph><cite>Ned Kelly</cite></ph></title> is technically correct, it nonetheless constitutes a workaround, and should not be used.