Table of Contents

DocFX does not infer navigation from the folder layout. Every site needs at least one TOC file, normally named toc.yml, that lists the pages in the order the reader should see them. The build turns each TOC into a toc.json file next to the pages (plus a toc.html when the default template is part of the build), and writes two metadata tags into every page: docfx:tocrel points to the TOC that belongs to that page and docfx:navrel points to the TOC that fills the navigation bar.

The same file type serves three purposes, and which one a file plays depends only on where it is and how other TOCs link to it:

The figure shows the files of the example site: the root TOC links to the folders guides/ and api/ with reference entries, and guides/toc.yml embeds a reusable fragment with a nested entry. The API TOC is generated by docfx metadata (see .NET API docs).

A TOC is a YAML tree of nodes. The root can be a list of nodes or a mapping with an items list; the mapping form is needed when the file carries its own properties such as order. The official page documents these node properties:

Source: DocFX docs: Table of Contents

The example below is the sidebar of the Pocket Units guides. It uses every node form: a plain page, a group with an expanded subtree, a nested TOC, a node with only a uid, and a group without a link.

Source: DocFX docs: Table of Contents

Building the site produces this guides/toc.json, formatted here for reading:

Source: output of docfx docfx.json (DocFX 2.81.0); the topicHref entries of the API nodes were left out of the listing to keep it short.

What this output shows:

DocFX 2.81.0 also reads a TOC written as a Markdown file named toc.md, where headings give the nesting level and each heading holds a link. The official TOC page documents only the YAML form, so prefer toc.yml for new sites.

Source: the DocFX reader for Markdown TOCs, MarkdownTocReader.cs

The build of this file produced one top node Intro with two children, Sub page and the external Docs site, with the same JSON structure as a YAML TOC. A line that does not match the supported patterns stops the build with an Invalid toc file error that names the line.

Every page is associated with one TOC. The rule from the official page is:

The decision above is a reading of the official text, not an additional rule from the source code. The effect was checked on the example site. The API pages PocketUnits.Converter.html are listed both by api/toc.yml and by guides/toc.yml (through the uid node and through the nested fragment). In the default build the page picked the nearest TOC:

Source: api/PocketUnits.Converter.html, generated by DocFX 2.81.0.

After adding order: -1 as the first line of guides/toc.yml, the same page pointed to the guides TOC:

Source: api/PocketUnits.Converter.html, generated by DocFX 2.81.0 after the change.

The namespace page api/PocketUnits.html kept toc.html, because only api/toc.yml listed it. A TOC with order therefore changes the sidebar of every page it lists, not only of one page.

To include one TOC in another, set href of a node to the path of a toc.yml file. The items of that file are placed under the node. This is also the way to reuse a list in several TOC files.

Source: DocFX docs: Table of Contents

Together with the entry href: reference/toc.yml in guides/toc.yml, this renders the node API types with the two children shown in the JSON above. The generated guides/reference/toc.json carries an order of 100, the default order of a nested TOC.

A reference TOC links to another TOC without copying its items. Set href to a folder and end the value with /. The node becomes a link to the first article of the TOC in that folder, and that folder’s TOC is the one that appears in the sidebar once the reader opens the page. Reference TOCs suit entries that lead to independent sections:

Source: DocFX docs: Table of Contents

If the node should open a different page than the first article, the data model also has a topicHref property. It was not documented on the official TOC page, so the following was only tried, not specified: a node with href: reference/ and topicHref: lengths.md produced the output keys href with the value lengths.html and tocHref with the value reference/toc.html in guides/toc.json, so the link opens lengths.html while the sidebar comes from reference/toc.yml.

The toc.yml that sits in the same folder as docfx.json fills the navigation bar at the top of every page. It normally uses reference TOCs, so each entry opens a section with its own sidebar. This is the root TOC of the example site; it also shows that an absolute URL is a valid href:

Source: DocFX docs: Table of Contents

The generated root toc.json resolved the two folders to their first articles and linked every page to it through docfx:navrel:

Source: root toc.json generated by DocFX 2.81.0.

The navigation bar can be switched off for the whole site or a page with the template metadata _disableNavbar, and the sidebar tree with _disableToc. Both are described in the docfx.json reference and belong to the template settings covered in Templates and Customization.

expanded: true asks the template to show a node’s children when the page opens. The official page states that it works only with the modern template. The key is carried to toc.json (as in the example above), but it is the template’s JavaScript that acts on it. The toc.html produced by the default template for the same file showed the group Conversions with its children in the markup and no expanded marker. This agrees with the documented limit; no browser was used to compare the two renderings visually.

The script of the modern template also marks the ancestors of the current page as expanded when the page loads, so expanded is mostly useful for sections that should be visible from the landing page.

docfx metadata writes its own TOC next to the API YAML files. For Pocket Units it produced api/toc.yml with the namespace and its types:

Source: output of docfx metadata (DocFX 2.81.0).

The shape of this TOC is controlled by docfx.json options of the metadata section: namespaceLayout (flattened by default, or nested), categoryLayout (flattened, nested or none; valid for the apiPage and markdown output formats only) and memberLayout. They are described in .NET API docs. Do not edit the generated file by hand; reference its folder from a hand-written TOC instead, as the root TOC above does with api/.

A TOC file is a document too, so metadata can be set for it. The precedence is fileMetadata first, then keys written in the toc.yml file itself, then globalMetadata. This lets a build override a setting of a generated TOC. The PDF properties pdf, pdfFileName, pdfCoverPage and pdfTocPage are set this way; see PDF Output. The mapping rules for docfx.json are in docfx.json.

TOC files are part of the build, so they must be in the build.content file list (the example lists toc.yml and guides/**/toc.yml); a TOC that the file list does not match is not processed. Broken entries are reported as warnings; these are the messages DocFX 2.81.0 printed when guides/toc.yml contained a missing file and an unknown UID:

Source: output of docfx docfx.json (DocFX 2.81.0).

The build still succeeded with 2 warnings. The broken node is kept in the output with its unresolved href for the missing file, and the node with the unknown UID appears without a name or link. Use --warningsAsErrors in continuous integration (see CLI) to turn such warnings into failures.

The C# conventions for XML documentation comments, which feed the API TOC, are covered in C# coding conventions and documentation; the build tooling around them is in C# build and tooling, and the Visual Basic equivalent in Visual Basic XML documentation.