Placement of indexterm elements

The indexterm element is pure metadata, and does not display. You should place index entries in the prolog section of the topic, or in the topicmeta section of the topicref in the ditamap only if the term is specific to a particular publication.

The alphabetical index of a publication is derived, during the publishing process, from index keyword terms placed by the author throughout topics in the document. Index keyword terms are defined through the indexterm element.

DITA allows indexterm elements to be placed in:

However, having index entries scattered throughout the text creates maintenance problems, and may lead to difficulties in translation and processing.

Where possible, indexterm elements should be placed in the topic prolog section, outside the body of the topic content. In the prolog, index entries must be contained within a keywords element.

When specific to a publication (and therefore not always applicable to the topic), the indexterm elements should be placed in the topicmeta section within the topicref element in the ditamap. An example of this may be a term that is used by one organisation but not others, where different ditamaps define output for different organisations.

Index terms should only be placed within the body text where topics are relatively long. In such cases, index entries in the output might otherwise point to the start of a section of content, rather than the point at which the term is mentioned.

When you need to place the index entry within the body of a topic, follow these placement guidelines:
Note: The contents of indexterm elements are never rendered in the output, including when the indexterm elements are inline within the body of the content. Thus, the mark-up: <p>The EJ25 <indexterm>turborcharger</indexterm> forced induction...</p> will render as The EJ25 forced induction....

In some cases, you may feel you want to use an indexterm at a particular point in the document where indexterm is not allowed. Although you may be able to technically work around the problem by inserting a phrase (ph) element and then inserting the indexterm element is the ph element, do not do this. Only insert an index term where the element is valid.