A ToC is used to define the Table of Contents (ToC) structure of a docset. The ToC can be described using either Yaml or Markdown.
The recommended format for ToCs is Yaml. The Yaml-based ToC format enables additional capabilities, such as auto-expansion of ToC nodes and automatic contextual ToC query string generation, which aren't available when using Markdown.
To build your ToC with Yaml, you should create a file named
toc.yml. Let's look at how a simple ToC would be represented:
- name: Tutorial href: tutorial.md items: - name: Step 1 href: step-1.md - name: Step 2 href: step-2.md - name: Step 3 href: step-3.md
The Yaml document itself is a list of ToC elements, each of which minimally has a
href. ToC nodes can also act as parents to other nodes. In this case, the child ToC nodes are represented by a list called
What follows is a larger example Yaml structure, which demonstrates more configuration options:
- name: Dev Sandbox href: index.md displayName: Home pdf_name: foo - name: Conceptual Pages href: ./conceptual/index.md expanded: true items: - name: Code Samples href: ./conceptual/code.md - name: Tables href: ./conceptual/tables.md - name: Reference Pages items: - name: IDictionary href: ./reference/System.Collection.IDictionary.yml - name: String href: ./reference/System.String.yml - name: Content Pages href: ./content/index.md - name: Hub Pages items: - name: Card Gallery href: ./hubPage/cardGallery.md - name: Landing Pages items: - name: Azure Architecture href: ./landingPage/azureCat.md - name: UWP href: ./landingPage/uwp.md - name: Engineering Excellence items: - name: Environment Setup href: ./eeds/environment-setup.md - name: Template Docs href: ./eeds/docs/index.md - name: Break Title Tests items: - name: System.Automation.String.Foo.Bar.Zip.Test() href: ./eeds/environment-setup.md - name: VMScaleSets-AzureRmDiagnosticsDscFixUp href: ./eeds/docs/index.md
Here's an explanation of all the properties available on a ToC node:
name(required) - A string name that is displayed for the ToC node (may not contain a colon (:) ).
displayName(optional) - An additional string value that doesn’t get displayed (yes, it's a very poor name) but is searched, in addition to
name, when doing ToC filtering.
href(optional) - A string that represents the link that the ToC node navigates to. Remember, nodes can exist just to parent other nodes, so this is still an optional property.
items(optional) - If a node has children, those are listed in the
itemsarray. The child nodes have the same available properties as listed above.
expanded(optional) - A boolean property (true/false) that determines if the node should be expanded by default when the ToC is loaded. Only one root-level node can be expanded on load.
maintainContext(optional) - A boolean property (true/false) that determiens if the ToC should be passed along with the link, for contextual ToC purposes. When using this property to reference an article in another docset, you don't have to encode the contextual ToC in the query string.
The Yaml format is more verbose than the Markdown format you will see next, but it enables taking advantage of the additional properties such as
maintainContext. Future capabilities coming to ToCs, such as versioning and experimentation, will similarly require Yaml.
In your docfx.json file, in your
content.files section, make sure to add the glob
"**/*.yml", otherwise the build system will not pick up the Yaml file.
Converting A Markdown ToC to Yaml
Ultimately, we'd like to move ToCs to the Yaml-based format, so all new ToCs should be created this way going forward. If you have an existing Markdown ToC that you need to migrate to Yaml, we have a conversion tool available for you.
The tool is named TocConverter, and is released on nuget.org. You can download it by running:
nuget install TocConverter in the console. (Make sure you have nuget installed first.)
The usage is as follows:
- Go to the folder where the tool was installed. This should be something like
- From within the tools folder, run
.\TocConverter.exe <path of toc markdown file> [path of generated toc yaml file]
Only the first parameter is required. This is the path of the
toc.md file which you need to be converted. The second parameter is optional. It is the path of where
toc.yml should be saved.
For simplicity, you may find it easier to copy the ToC.md file into the tools folder so that you don't have to worry about typing complex paths.
Adding metadata for Toc
Metadata is only supported in Yaml format Toc. If you wish to add metadata in Markdown format Toc, please follow the previous section to convert it to Yaml format.
metadata: metadata_key: metadata_value items: - name: Dev Sandbox href: index.md displayName: Home pdf_name: foo - name: Conceptual Pages href: ./conceptual/index.md expanded: true items: - name: Code Samples href: ./conceptual/code.md - name: Tables href: ./conceptual/tables.md - name: Reference Pages items: - name: IDictionary href: ./reference/System.Collection.IDictionary.yml - name: String href: ./reference/System.String.yml - name: Content Pages href: ./content/index.md
As the sample above, you need to add an array named
items in the top of the original toc structure. Then add a
metadata field, the value of
metadata is a dictionary, with the metadata name and value pair which you want to assign to the Toc.
To build your ToC with Markdown, you should create a file named
toc.md. Let's look at how a simple ToC would be structured:
# Tutorial ## Step 1 ## Step 2 ## Step 3
The above example illustrates a parent topic "Tutorial" with three children Step 1-3.
We use standard Markdown link syntax to specify the target topic of the toc node. For example:
# [Tutorial](tutorial.md) ## [Step 1](step-1.md) ## [Step 2](step-2.md) ## [Step 3](step-3.md)
If a toc node is not a link, it will become a container node: it can contain children and it will be just a expanding/collapsing node.
Some times you would like to split your giant ToC file to multiple smaller managable pieces. OPS also supports this approach. During build, we will find the ToC files referenced by the main ToC and generate a combined ToC view.
You can find 2 different syntax below, as we support either referencing another ToC file, or a folder.
- If you include a toc.md file, the entry you use to include the file would be rendered as a control to expand or collapse the sub ToC.
- If you include a folder, OPS will NOT extract the toc.md in that folder, but use the 1st entry in the toc.md file in that folder as the entry in the referencing TOC.
# [Root Index](index.md) ## [1-1 topic](1-1topic.md) ## [1-2 topic](1-2topic.md) ## [ref 2-1 toc](level-2-1/TOC.md) ## [ref 2-2 folder](level-2-2/)
The level of ToC entry would be the calculated a sum from the referencer and referencee ToC file for the specific entry.
TOC common issues:
- Remove the root folder, some paths had the root folder in it and it is not needed.
- Good: marketplace/overview.md
- Not good: /docs/marketplace/overview.md
- Others had an extra slash
- Good: collaborate/overview.md
- Not good: /collaborate/overview.md
- Others had the wrong abbreviation for the path:
- Good: ./docs/setup-admin/get-started.md
- Not good: ../ docs/setup-admin/get-started.md
OP supports multiple level of nested ToC - 6 levels maximum. OP doesn't support nested TOCs between docsets or repos.
- The ToC for Open Publishing is a self-contained ToC, not integrated into the global MSDN/TN ToC.
- You can use an external link to connect the Open Publishing ToC to your MSDN/TN Global ToC.
- Since Markdown only supports 6 levels of header, we'll only support 6 levels of ToC for now. This can be extended in the future.
- You cannot reference a file outside a docset/folder.
- toc.md cannot contain arbitrary Markdown content. For example, you cannot have images in it. All content that are not headers will lead to a build error.
A localized ToC is maintained in sync with English via the handoff and handback process. The ToC file will be included in the handoff package.
ToC in Markdown
Suggested ToC Structure
To ensure quality, standarization and a great user experience we recommend that the ToC follows this structure:
# [Overview](overview.md) ## [topic-related-to-Overview](topic-related-to-Overview.md) # [Getting Started](Getting-Started.md) ## [topic-related-to-gettingstarted](topic-related-to-gettingstarted.md) # [How to](How-to.md) ## [topic-related-to-hot-to](topic-related-to-hot-to.md) # [Reference](reference.md) ## [topic-related-to-reference](topic-related-to-reference.md) # [Resources](resources.md) ## [topic-related-to-resources](topic-related-to-resources.md)
Topic across Azure follow this ToC guideline for consistency and quality, example: Azure Express Route.
Azure Standarized TOC: