Table of Contents (toc) Files

Now that we have our sample content files we can create a table of contents (toc) file. A toc file defines the key entry points into the HTML content files by mapping a topic label to a reference in one of the HTML files. 

Applications that are being migrated to the platform can reuse existing documentation by using the toc file to define entry points into that documentation.

A plug-in can have one or more toc files. Our example documentation is organized into three main categories: concepts, tasks and reference. How do we make toc files that represent this structure?

We could make one large toc file, or we could create a separate toc file for each main category of content. This decision should be made according to the way your documentation teams work together. If a different author owns each category, it might be preferable to keep separate toc files for each category.  It is not dictated by the platform architecture.

In this example, we will create a toc file for each major content category. For such a small number of files, having separate toc files for each category may not be necessary.  We will build this example as if we had many more files or had separate authors who own each content category.

Our files look like this:

toc_Concepts.xml

   <toc label="Concepts">
      <topic label="Concept1" href="html/concepts/concept1.html">
         <topic label="Concept1_1" href="html/concepts/concept1_1.html"/>
         <topic label="Concept1_2" href="html/concepts/concept1_2.html"/>
      </topic> 
   </toc>

toc_Tasks.xml

   <toc label="Tasks">
      <topic id="plainTasks" label="Plain Stuff">
         <topic label="Task1" href="html/tasks/task1.html"/>
         <topic label="Task2" href="html/tasks/task2.html"/>
      </topic>
      <topic id="funTasks" label="Fun Stuff" >
         <topic label="Task3_1" href="html/tasks/task3_1.html"/>
         <topic label="Task3_2" href="html/tasks/task3_2.html"/>
      </topic>
   </toc>

toc_Ref.xml

   <toc label="Reference">
      <topic label="Ref1" href="html/ref/ref1.html"/>
      <topic label="Ref2" href="html/ref/ref2.html"/>
   </toc>

A topic can be a simple link to content.  For example, "Task1" provides a label and an href linking to the content.  A topic can also be a hierarchical grouping of sub topics with no content of its own.  For example, "Fun Stuff" has only a label and sub topics, but no href .  Topics can do both, too.  "Concept1" has an href and sub topics.

Dynamic content

Dynamic content is available for the table of contents in the form of filters and extensions. For example, you may want a topic to show up in the table of contents only when running on a specific operating system.

Includes are not supported here because they are not needed; use links instead.