Content Placement Options

This topic describes the various content placement options available that allow you to define how the conceptual content and reference content are arranged in the table of contents.

• Automatic Placement Options
• Explicit Placement Options
• Microsoft Help Viewer Placement Options
• Microsoft Help Viewer Root Content Container

In the absence of any explicit instructions in the content layout file, conceptual content topics will be placed according to the Content Placement project property. If set to Above Namespaces (the default), the conceptual content topics will appear before the namespace topics. If set to Below Namespaces, they will appear after the namespace topics.

In Help 1, markdown, and website output, if no conceptual content is present or no topic is marked as the default topic, the root namespaces page will be selected as the default topic for the help file.

For finer control over the placement of the API content and selection of the default topic, use the options available in the content layout file editor.

• The Use as the default topic option can be used to mark a conceptual topic as the default topic for Help 1, markdown, and website output. This option has no effect in MS Help Viewer files as there is no option to specify a default topic.

• A conceptual topic anywhere within the content layout file can be marked as the API content insertion point using the API Content option. You can choose to insert the API content below the selected topic, above the selected topic, or as a child of the selected topic. When an insertion point is defined, the Content Placement project property is ignored.

In addition to the above placement options, you have some additional control over how your help file content is parented when using the Microsoft Help Viewer output format. These options take effect after the above options have been applied.

• The TOC Parent Id and TOC Parent Version properties allow you to specify where your help file content is parented. If left at their default settings, your content will appear in the main table of contents. If you specify a parent ID and version, you can place your content below an existing topic in the help file viewer. You can find the values to use by going to the parent topic in the help viewer, viewing the source for the page, and finding the Microsoft.Help.Id and Microsoft.Help.TopicVersion metadata items.

• The TOC Order property allows you to specify the sort order for your topics within the parent item. If left set to the default, your topics are given a sort order starting at zero and increment by one for each subsequent topic. If set to a specific value, they will begin numbering from that value and increment by one for each subsequent topic. If parenting your content within an existing topic, you can view the page source for its existing sub-topics to find the highest Microsoft.Help.TocOrder value.

    Note

  If a topic order matches an existing topic in the parent's sub-topics, the topics with the duplicate value will be sorted alphabetically.

By default, the topics in a help viewer file will be listed one after the other at the point they are parented. Typically, this is not appropriate and you will want to group the topics beneath a single root content container. To do so, you can do one of the following things to accomplish this task:

• If you are only generating MS Help Viewer output, you can create a topic to serve as the root container node and place all other topics as sub-topics of the first topic in the content layout file.

• If you are generating multiple help formats from a single help file builder project, the option above may not be desirable. For example, if generating both MS Help Viewer and website output, you may not want the website table of content to be grouped beneath a single root content container node.

  To remedy this problem, the content layout file editor will allow you to add a topic and mark it as the root content container with the Use as MS Help Viewer root container option. The root container topic must have its Show in the table of contents option unchecked so that it does not appear in the table of contents for the other output formats. As such, it cannot have any sub-topics that are visible either.

  When you build MS Help Viewer Output, the help file builder will automatically insert the topic as the root content container with all the other content in the project as sub-topics beneath it. The conceptual and reference content ordering options noted above will be applied to the sub-topics. The help viewer parenting properties noted above will be applied to the root container node. For other help formats produced by the build, the root content topic is ignored.

Other Resources