Edit online

The table of contents is a hierarchy of topic titles with links to the topic content.

For plain maps, the TOC is automatically generated. For DITA bookmaps, you will need to add a <toc> element in the <booklists> element (inside the <frontmatter>):
<bookmap>
  ...
  <frontmatter>
    <booklists>
      <toc/>
      <figurelist/>
      <tablelist/>
    </booklists>
  </frontmatter>
  ...
  ...

Edit online

In the merged map file, the <opentopic:map> contains a hierarchy of <topicref> elements, or other elements (such as <chapter> or <part>) that are specializations of <topicref>.

Each of the <topicref> elements include a metadata section that includes the topic title.

 <bookmap ...>

 <oxy:front-page> ... </oxy:front-page>
 <oxy:front-matter> ... </oxy:front-matter>

 <opentopic:map xmlns:opentopic="http://www.idiominc.com/opentopic" class="- toc/toc ">

   <oxy:toc-title xmlns:oxy="http://www.oxygenxml.com/extensions/author" empty="true" 
       class="- toc/title "/>

   <booktitle class="- topic/title bookmap/booktitle ">
       <booklibrary class="- topic/ph bookmap/booklibrary ">Retro Tools</booklibrary>
       <mainbooktitle class="- topic/ph bookmap/mainbooktitle ">Tasks</mainbooktitle>
       <booktitlealt class="- topic/ph bookmap/booktitlealt ">Product Tasks</booktitlealt>
   </booktitle>


   <chapter is-chapter="true"
       class="- map/topicref bookmap/chapter " href="#unique_5" type="topic">
       <topicmeta class="- map/topicmeta " data-topic-id="installing">
           <navtitle href="#unique_5" class="- topic/navtitle ">Installing</navtitle>
           ...
       </topicmeta>

       <topicref class="- map/topicref " href="#unique_6" type="task">
           <topicmeta class="- map/topicmeta " data-topic-id="installstorage">
               <navtitle href="#unique_6" class="- topic/navtitle ">Installing</navtitle>
                    ...
           </topicmeta>
                ...                
       </topicref>
            ...
   </chapter>

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="- bookmap/bookmap map/map map bookmap" ...>

 <div class="- front-page/front-page front-page"> ... </div>
 <div class="- bookmap/frontmatter frontmatter"> ... </div>

 <div class=" toc/toc toc">

  <div class="toc/toc-title toc-title" empty="true"/>

  <div class="- topic/title bookmap/booktitle booktitle">
       <div class="- topic/ph bookmap/booklibrary booklibrary">Retro Tools</div>
       <div class="- topic/ph bookmap/mainbooktitle mainbooktitle">Tasks</div>
       <div class="- topic/ph bookmap/booktitlealt booktitlealt">Product Tasks</div>
  </div>


  <div is-chapter="true"
   class="- map/topicref bookmap/chapter topicref chapter " href="#unique_5" type="topic">
   <div class="- map/topicmeta topicmeta" data-topic-id="installing">
       <div href="#unique_5" class="- topic/navtitle navtitle">Installing</div>
       ...
  </div>

  <div class="- map/topicref  topicref chapter " href="#unique_6" type="task">
       <div class="- map/topicmeta topicmeta" data-topic-id="installstorage">
           <div href="#unique_6" class="- topic/navtitle navtitle">Installing</div>
                ...
  </div>
                ...                
 </div>
            ...
</div>
Note: The <oxy:toc-title> element is used as a placeholder for the name of the TOC. For instance, you can use the string "Contents", specified on a pseudo element, in the CSS.

Edit online

The built-in CSS rules are in: [PLUGIN_DIR]/css/print/p-toc.css.

Edit online

Note: Each of the items from the table of contents is an element that has the map/topicref class.
The following example uses the italic font for the label and changes the color and style of the connecting line between the title and the page number.

In your customization CSS, add the following two selectors:

/* The toc item label - the topic title */
*[class ~= "map/topicref"] *[class ~= "topic/navtitle"] {
    font-style:italic;
    color: navy;
}

/* The dotted line between the topic name and the page number. */
*[class ~= "map/topicref"] *[class ~= "topic/navtitle"]:after {
    content: leader('-') target-counter(attr(href), page);
    color: navy;
}

And if you need to alter the indent of the nested table of content items, use the following selector:

*[class ~= "map/topicref"] *[class ~= "map/topicref"] {
    margin-left: 1em;
}

The numbers can be styled like this:

*[class ~= "map/topicref"] > *[class ~= "map/topicmeta"]:before,
*[class ~= "map/topicref"] 
    > *[class ~= "map/topicmeta"] > *[class ~= "topic/navtitle"]:before{
  color:blue;
}

The following is an example of customizing the font size for the items representing chapters. The chapters are level one topics and are marked in the merged DITA document TOC with the attribute @is-chapter.

*[class ~= "map/topicref"][is-chapter = "true"]  > *[class ~= "map/topicmeta"] > *[class ~= "topic/navtitle"]{
  font-size:2em; 
}

Edit online

In the built-in CSS, there is a page named table-of-contents. The default is to have the word 'Contents' in its header (this is localized, using the toc-header string defined in the p-18n.css) alternating in the left or right side of the header:

@page table-of-contents:left {
    @top-left {
        content: string(toc-header) " | " counter(page, lower-roman);
        font-size: 8pt; 
    }
}
@page table-of-contents:right {
     @top-right {
         content: string(toc-header) " | " counter(page, lower-roman);
         font-size: 8pt; 
     }
}

If you need to change this string, or change the color, you should use the following @page selectors as a starting point in your customization CSS:

@page table-of-contents:left {
    @top-left {
        content: "My publication table of contents | " counter(page, lower-roman);
        color:red;
    }
}
@page table-of-contents:right {
     @top-right {
        content: "My publication table of contents | " counter(page, lower-roman);
        color:red;
     }
}

Edit online

In your customization CSS, add the following snippet for the table-of-contents page:

@page table-of-contents{
    -oxy-initial-page-number: auto-odd;
}

Edit online

To display a topic before the table-of-contents page, follow these steps:
  1. Make sure the topic is referenced on the first level in the DITA map.
  2. Set the @outputclass to before-toc on the <topicref>.
<topicref href="pathToMyTopic" outputclass="before-toc">

Result: When the PDF is processed, the topic will automatically appear before the table of contents.

Edit online

To display the short descriptions from the topics in the table of contents, you need to make the <shortdesc> element visible.

The following example only makes the short descriptions associated with the chapters visible. The chapters are level one topics and are marked in the merged DITA document TOC with the attribute @is-chapter.

In your customization CSS, add the following CSS selector:

*[class ~= "map/topicref"][is-chapter = "true"] > *[class ~= "map/topicmeta"] > *[class ~= "map/shortdesc"] {
  display:block; /* The default is none - the shortdesc is hidden. */
  color:gray;
}
Note: If you need all the TOC item short descriptions to be visible, remove the [is-chapter] condition.

Edit online

To remove entries from the table of contents, set the @toc="no" attribute on the topicrefs from the map that need to be removed. This is sometimes desirable for the topics listed in the frontmatter or backmatter when using a bookmap.

Edit online

To hide the TOC, you have multiple options:
  • Use a DITA bookmap instead of a DITA map, and omit the <toc> element from the <booklists>. An example bookmap can be found in the DITA 1.3 Spec. This is the best approach.
  • Use the transformation parameter: hide.frontpage.toc.index.glossary.
  • Use a display:none property to hide the element that contains the TOC structure, and also remove it from the PDF bookmarks tree:
    *[class ~= "map/map"] > *[class ~= "toc/toc"] {
      display:none;
    }
    
    *[class ~= "map/map"] > *[class ~= "toc/toc"] > *[class ~= "toc/title"]{
      bookmark-label: none;	
      -ah-bookmark-label: none;
    }