 | Defining the Table of Contents Layout |
The following information only applies if a site map file is not defined in the project. When using a site map file, its layout definition overrides all file-level definitions. See the Site Map File Editor topic for details.
 Caution |
|---|
Deprecated The additional content model of adding extra content to a help file has been deprecated. While it will continue to be supported and will not be removed, it will not receive any more features or updates. Going forward, conceptual content is the preferred method of adding non-reference content to the help file. The additional content feature can still be used to override stock content and add supporting files to the help file. |
All HTML files copied as additional content will automatically be added to the help file's table of contents. Subfolders will also create folder entries within the table of contents and the HTML files within them become children of the folder entry in the table of contents. This makes it fairly simple to create hierarchical content with matching table of contents entries. The table of contents will mimic the folder structure on disk.
The help file builder scans each HTML file for the following tags and specially formatted comments that allow you to define the related properties of the table of contents entries. They can appear anywhere in the file.
<title>Page Title</title> - The value from the title tag in the HTML file is used as the title in the table of contents. If no title tag is found, the filename without the path and extension is used as the title.
<!-- @TOCExclude --> - This special comment can be used to exclude the page from the table of contents. The file will still be copied to the output folder but will not appear in the table of contents. Instead, a link to it must exist from another help page. This is also useful for setting the title and sort order on folder entries without associating a page with the folder entry in the table of contents. See below for more information.
<!-- @DefaultTopic --> - This special comment is used to indicate that the page should be selected as the default topic for the help file. If multiple pages contain this comment, the last one seen will be used as the default topic. If no additional content items are defined or none are marked as the default topic, the root namespaces page is selected as the default topic.
<!-- @SortOrder nnn --> - This special comment is used to set the sort order of the item within the group where "nnn" represents an integer value. The "group" is all other additional content table of contents entries at the same level as the current item. In the absence of a sort order indicator, table of contents entries are sorted alphabetically. By specifying a sort order, you can rearrange the entries in a different order. Items within a group that have the same sort order value will also sort alphabetically. Items without a sort order indicator are placed below those with a sort order indicator and are sorted alphabetically.
<!-- @SplitTOC --> - This special comment is used to indicate that the table of contents should be split by the API content. It is only valid on table of contents entries that appear at the root level. All table of contents entries prior to the entry with this tag will appear before the API content. The entry with the tag and all entries following it will appear after the API content.
By default, folder entries in the table of contents will not have any HTML page associated with them and will not show a specific page in the help file when selected. The title will be the folder name and they will be sorted alphabetically within the same group of items below any items that have a sort order indicator. You can control these properties for folder entries by placing an HTML file in the folder that has the same name as the folder (i.e. place a file called OtherContent.html in the OtherContent\ folder to set its properties). If the @TOCExclude comment does not appear in the file, the associated page will be displayed when the folder is selected in the table of contents. Below are a couple of examples:
<!-- @TOCExclude --> <!-- @SortOrder 3 --> <title>Other Content</title>
The example above sets the sort order and title of the folder entry but does not display anything when the folder is selected as it contains the @TOCExclude comment.
<html> <head> <title>Folder Entry with a Content Page</title> </head> <!-- @SortOrder 2 --> <body> This is a content page for a folder entry in the table of contents. </body> </html>
The example above sets the sort order and title of the folder entry and specifies content that will be displayed when the folder is selected as the @TOCExclude comment is omitted. It could also be made the default topic by adding the @DefaultTopic comment.
See Also