Edit online

Table of Contents

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

Table of Contents - XML Fragment

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

How to Increase TOC Depth

By default, only the first three levels of topics are displayed in the Table of Contents of the PDF output.

The CSS rule (see Table of Contents - Built-in CSS) that hides topics on higher levels is: 

/* Hide sections below level 3. */
*[class ~= "map/topicref"][is-chapter] >
*[class ~= "map/topicref"]:not([is-chapter]) >
*[class ~= "map/topicref"] >
*[class ~= "map/topicref"] {
  display: none;
}
If you want to increase the TOC depth so that topic references on level 3 or higher are visible, you can overwrite this rule in your customization CSS like this:
*[class ~= "map/topicref"][is-chapter] >
*[class ~= "map/topicref"]:not([is-chapter]) >
*[class ~= "map/topicref"] >
*[class ~= "map/topicref"]{
  display:block;
}
If the args.css.param.numbering parameter is set to a value other than shallow, you also need to add the following rules in your customization CSS:
*[class ~= "map/map"][numbering ^= 'deep']
*[class ~= "map/topicref"][is-chapter]:not([is-part]) > 
*[class ~= "map/topicref"] > 
*[class ~= "map/topicref"]
*[class ~= "map/topicref"] {
  counter-increment: toc-chapter-and-sections;
}

*[class ~= "map/map"][numbering ^= 'deep']
*[class ~= "map/topicref"][is-chapter]:not([is-part]) > 
*[class ~= "map/topicref"] > 
*[class ~= "map/topicref"]
*[class ~= "map/topicref"] > 
*[class ~= "map/topicmeta"] + *[class ~= "map/topicref"] {
  counter-reset: toc-chapter-and-sections;
}

*[class ~= "map/map"][numbering ^= 'deep']
*[class ~= "map/topicref"][is-chapter]:not([is-part]) > 
*[class ~= "map/topicref"] > 
*[class ~= "map/topicref"] > 
*[class ~= "map/topicref"]
*[class ~= "map/topicref"] > *[class ~= "map/topicmeta"]:before {
  content: counters(toc-chapter-and-sections, ".") ". ";
}
Edit online

How to Style the Table of Contents Entries

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

How to Change the Header of the Table of Contents

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;
     }
}
Important: The first page from the table of contents does not have any content displayed in the header. The default CSS contains rules that disable the content. If you need to also display the numerals on the first page, use the following:
@page table-of-contents:first:left {
  @top-left {
    content: string(toc-header) " | " counter(page, lower-roman);
  }
}
@page table-of-contents:first:right {
   @top-right {
     content: string(toc-header) " | " counter(page, lower-roman);
   }
}
Edit online

How to Make the Table of Contents Start on an Odd Page

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

How to Display a Topic Before the Table of Contents

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

How to Display Short Descriptions in the TOC

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

How to Remove Entries from the TOC

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

How to Hide the TOC

To hide the TOC, you have multiple options:
  • [Recommended] Use a DITA <bookmap> instead of a <map>, and omit the <toc> element from the <booklists>. An example bookmap can be found in the DITA 1.3 Spec.
  • 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;
}