Metadata in maps and topics
Information about topics can be specified as metadata on the map, as attributes on the <topicref> element, or as metadata attributes or elements in the topic itself:
- DITA map: Metadata elements
At the map level, properties can be set by using metadata elements. They can be set for an individual topic, for a set of topics, or globally for the entire document. The metadata elements are authored within a <topicmeta> element, which associates metadata with the parent element and its children. Because the topics in a branch of the hierarchy typically have some common subjects or properties, this is a convenient mechanism to define properties for a set of topics. For example, the <topicmeta> element in a <relcolspec> can associate metadata with all the topics that are referenced in the <reltable> column.
A map can override or supplement everything about a topic except its primary title and body content. All the metadata elements that are available in a topic also are available in a map. In addition, a map can provide alternate titles and a short description. The alternate titles can override their equivalent titles in the topic. The short description in the map MAY override the short description in the topic if the <topicref> element specifies a @copy-to attribute.
- DITA map: Attributes of the <topicref> element
- At the map level, properties can be set as attributes of the <topicref> element.
- DITA topic
- Within a topic, authors can either set metadata attributes on the root element or add metadata elements in the <prolog> element.
How metadata set at both the map and topic level intersects
In a topic, the metadata elements apply to the entire topic. In a map, they supplement or override any metadata that is provided in the referenced topics. When the same metadata element or attribute is specified in both a map and a topic, by default the value in the map takes precedence; the assumption here is that the author of the map has more knowledge of the reusing context than the author of the topic. The @lockmeta attribute on the <topicmeta> element controls whether map-specified values override values in the referenced topic.
The <navtitle> element is an exception to the rule of how metadata specified by the <topicmeta> element cascades. The content of the <navtitle> element is used as a navigation title only if the @locktitle attribute of the parent <topicref> element is set to "yes".