Search results

DITA: Index entries

You can add index entries to topics. Even if you don't see the value in providing an index, index entries can help searches find the right topics.

There are various approaches for adding indexes, but here's a typical way to add index entries.

Sponsored

In the prolog | metadata | keywords element of a topic, add index terms The prolog element comes just after the shortdesc element (which follows the title). Here's a sample: 
<title>My Title</title>
 <shortdesc/>
<prolog>
    <metadata>
      <keywords>
        <indexterm>cars</indexterm>
      </keywords>
    </metadata>
  </prolog>
You can also nest index entries inside of each other to create parent-child relationships among the index terms: 
  <prolog>
    <metadata>
      <keywords>
        <indexterm>cars
                <indexterm>sedan</indexterm>
        </indexterm>
      </keywords>
    </metadata>
  </prolog>
The result in the index will look like this: 
cars
  - sedan

When you want to create a "see" entry for an index, code it like this:

   <indexterm>vehicle
   <index-see>car</index-see>
</indexentry>

The result of the index-see element is the following:

    vehicle, see car

If you want to include a page number with the see also reference, write it like this:

    <indexterm>vehicle
   <index-see-also>car</index-see-also>
</indexentry>
    </indexterm>

The output will look like this:

    vehicle ..... 23
           see also car

Keep in mind that index entries added to the prolog section will include page numbers pointing to the location of the prolog. Since most topics are short, this isn't a problem. Also, since the online help is usually the main deliverable, it's also not a problem. However, you can also add index entries in the middle of your topics. (But apparently this causes some problems, especially with translation.)

Also, some PDF renderers don't include page numbers to index entries. At any rate, since PDF isn't usually the main deliverable, this is not a concern with index terms.

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, agent skills, tech comm careers, and more. Check out my AI courses for more on the latest in AI and tech comm. If you're looking for info about documenting APIs, see my API documentation course.

If you're a technical writer and want to keep on top of the latest trends in tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me.

Finally, I want to note a couple of things. I usually write the first drafts of my posts myself and then use AI to improve accuracy, clarity, and detail in places, so my writing is a mix of human and AI. (Hopefully that's not too off-putting.) Also, the opinions I express on my blog are my own perspectives, not those of my employer.

© 2026 Tom Johnson