Edit online

Index

The content of an <indexterm> element is used to produce an index entry in the generated index. You can nest <indexterm> elements to create multi-level indexes. The content is not output as part of the topic content, only as part of the index tree.

To add an index to your publication, you just need to add <indexterm> elements inside the <prolog> section (inside a <metadata> element):

  <title>The topic title.</title>
  <prolog>
    <metadata>
      <keywords>
        <indexterm>Installing <indexterm>Water Pump</indexterm></indexterm>
      </keywords>
    </metadata>
  </prolog>
  <body>
    .....

or in the content itself:

...
<p>Open the lid then turn the body pump to the right. 
<indexterm>Installing <indexterm>Water Pump</indexterm></indexterm> 
</p>
...

If you are using a bookmap, you need to specify where the index list should be presented (for instance in the backmatter of the book. Technically, it is possible to also add it to the frontmatter, but this is unusual). This is done using an <indexlist> element in the <booklists> element (inside the <backmatter>):

<bookmap>
    ...
    <chapter href="tasks/troubleshooting.dita">
      ...
    </chapter>
    <backmatter>
        <booklists>
            <indexlist/>
        </booklists>
    </backmatter>
</bookmap>

For plain maps, the index list is automatically added at the end of the publication, with no need to modify the map.

Edit online

Index - XML Fragment

In the merged map file, the structure that holds the index tree is the <opentopic-index:index.groups> element.

<map class="- map/map " >
    <oxy:front-page>
        ... 
    </oxy:front-page>
    <opentopic:map xmlns:opentopic="http://www.idiominc.com/opentopic">
        ...
    </opentopic:map>
    <topic class="- topic/topic ">
        <title class="- topic/title ">Request Support</title>
       ...
    </topic>
    <opentopic-index:index.groups id="d16e5548">
      ...
    </opentopic-index:index.groups>
</map>
Each of the groups contain:
  • A label, the starting letter ("T" in the following example).
  • A tree of <opentopic-index:index.entry> elements.
<opentopic-index:index.group>

 <opentopic-index:label>T</opentopic-index:label>

  <opentopic-index:index.entry value="table of contents">
    <opentopic-index:formatted-value>table of contents</opentopic-index:formatted-value>
    <opentopic-index:refID value="table of contents:">
        <oxy:index-link xmlns:oxy="http://www.oxygenxml.com/extensions/author" 
               href="#d16e3988"> [d16e3988]
        </oxy:index-link>
    </opentopic-index:refID>
    <opentopic-index:index.entry value="change header">
        <opentopic-index:formatted-value>change header</opentopic-index:formatted-value>
        <opentopic-index:refID value="table of contents:change header:">
           <oxy:index-link xmlns:oxy="http://www.oxygenxml.com/extensions/author" 
                href="#d16e4176">
                [d16e4176] </oxy:index-link>
        </opentopic-index:refID>
    </opentopic-index:index.entry>
    <opentopic-index:index.entry value="style">
        <opentopic-index:formatted-value>style</opentopic-index:formatted-value>
        <opentopic-index:refID value="table of contents:style:">
            <oxy:index-link xmlns:oxy="http://www.oxygenxml.com/extensions/author" 
                href="#d16e4120">
                [d16e4120] </oxy:index-link>
        </opentopic-index:refID>
  </opentopic-index:index.entry>
 </opentopic-index:index.entry>
</opentopic-index:index.group>
Each of the entries contain:
  • The formatted value (<opentopic-index:formatted-value>).
  • A link to the publication content (<opentopic-index:refID>/<oxy:index-link>).
  • Possibly other child entries.

For the DITA Map PDF - based on HTML5 & CSS transformation type, the merged map is further processed resulting in a collection of HTML5 <div> elements. These elements preserve the original DITA @class attribute values and add a new value derived from the DITA element name.

 <div class="- map/map map" >
    <div class="front-page/front-page">
        ... 
    </div>
    <div class="toc/toc toc">
        ...
    </div>
    <div class="- topic/topic topic">
        <div class="- topic/title title">Request Support</title>
       ...
    </div>
    <div class=" index/groups groups">
      ...
    </div>
</map>
The index group content becomes:
<div class=" index/group group">
  <div class=" index/label label">T</div>

  <div class=" index/entry entry">
    <div class=" index/formatted-value formatted-value">table of contents</div>
    <div class=" index/refid refid">
        <div class=" index/link link"
               href="#d16e3988"> [d16e3988]
        </div>
    </div>
    <div class=" index/entry entry">
        <div class=" index/formatted-value formatted-value">change header</div>
         <div class=" index/refid refid">
             <div class=" index/link link"
                href="#d16e4176"> [d16e4176] </div>
        </div>
    </div>
    <div class=" index/entry entry">
        <div class=" index/formatted-value formatted-value">style</div>
        <div class=" index/refid refid">
            <div class=" index/link link"
                href="#d16e4120"> [d16e4120] </div>
        </div>
    </div>
  </div>
</div>
Edit online

Index - Built-in CSS

All index styling is found in: [PLUGIN_DIR]css/print/p-index.css.

Edit online

How to Style the Index Page Title and the Grouping Letters

In your customization CSS, add the following CSS rules:

*[class ~= "index/groups"] *[class ~= "index/group"] *[class ~= "index/label"] {
    font-size:1.5em;
    color:navy;
}

*[class ~= "index/groups"]:before {
    content: "- Index - ";
    color:navy;
    font-size: 4em;
}
The result is:

Edit online

How to Style the Index Terms Labels

In your customization CSS, add the following CSS rule:

*[class ~= 'index/groups'] *[class ~= 'index/formatted-value'] {
    font-style:oblique;
    color:gray;
}
The result is:
Screenshot of the Index section from a publication
Edit online

How to Add Filling Dots Between the Index Labels and the Page Numbers

Suppose you want the leader CSS content to generate a row of dots. It is necessary that the parent entry has the text justified.

In your customization CSS, add the following CSS rule:


*[class~="index/formatted-value"],
*[class~="index/refid"] {
    display:inline;
}


/* Hide the sequences of links that actually do not contain links. */
*[class~="index/group"] *[class ~= "index/entry"] > *[class~="index/refid"]{
    display:none;
}
*[class~="index/group"] *[class ~= "index/entry"] > *[class~="index/refid"]:has(*[class~="index/link"]){
    display:inline;
}

*[class~="index/group"] *[class~="index/entry"] {
    text-align:justify;
}
*[class~="index/group"] *[class ~= "index/entry"] > *[class~="index/refid"]:before{
    content:leader('.');
}

The output now contains the dots:

Screenshot with the Index section from a publication
Edit online

How to Change the Index Page Number Format and Reset its Value

The page number is reset at the beginning of the index page by the built-in CSS rule:

*[class ~= "index/groups"] {
        counter-reset: page 1;
}

If you want to start the page counter from a different initial number, just change the value of this counter. For example, to continue the normal page counting, use:

*[class ~= "index/groups"] {
        counter-reset: none;
}

If you need to style the page number differently (for example, using decimals), add the following CSS rule in your customization CSS:

@page index {
        @bottom-center      {          content: counter(page, decimal) }
}
Edit online

How to Display Index Terms and Page Numbers inline

By default, the page numbers that reference each index term are displayed beneath the term. This behavior can be overridden to render page numbers inline with their associated terms. The goal here is to render the following elements on the same line:
index/formatted-value
This element contains the index term text.
index/refid
This element contains the list of links for the given term (as page numbers).
To accomplish this, simply add the following CSS rule in your customization CSS:
*[class ~= "index/formatted-value"],
*[class ~= "index/refid"] {
  display: inline;
}
Edit online

How to Impose a Table-like Index Layout

For a more complex inline layout (requiring greater alignment constraint), using inline-block instead of inline provides a way to emulate a table-like appearance.

To implement this table layout, include the following CSS rule in your customization CSS:
Notes:
  • The 45% fixed width is used (slightly under 50% to keep content on the same line despite possible margins/paddings).
  • Hierarchical layout is achieved by applying progressive padding to the formatted value text.
*[class ~= "index/formatted-value"],
*[class ~= "index/refid"] {
  display: inline-block;
  width: 45%;
}

/* Hide the sequences of links that actually do not contain links. */
*[class ~= "index/groups"] *[class ~= "index/entry"] > *[class ~= "index/refid"] {
  display: none;
}
*[class ~= "index/groups"] *[class ~= "index/entry"] > *[class ~= "index/refid"]:has(*[class ~= "index/link"]) {
  display:inline-block;
}

/* Move the nesting of indexterms from margin to padding */
*[class ~= "index/groups"] *[class ~= "index/entry"] {
  margin-left: 0;
}
*[class ~= "index/groups"]
*[class ~= "index/entry"]
*[class ~= "index/formatted-value"] {
  padding-left: 0.2em;
}
*[class ~= "index/groups"]
*[class ~= "index/entry"]
*[class ~= "index/entry"]
*[class ~= "index/formatted-value"] {
  padding-left: 0.4em;
}
*[class ~= "index/groups"]
*[class ~= "index/entry"]
*[class ~= "index/entry"]
*[class ~= "index/entry"]
*[class ~= "index/formatted-value"] {
  padding-left: 0.6em;
}

/* Some styling */
*[class ~= "index/formatted-value"],
*[class ~= "index/refid"] {
  padding: 0.2em;
  background-color: #EEEEEE;
}

You will obtain this result:

To avoid bleeding of the index term label, you may need to mark it as being hyphenated:
*[class~="index/formatted-value"] {
    hyphens:auto;
}
To activate hyphenation, see: How to Enable Hyphenation for Entire Map.