Table of Contents
Tip

The docs as explained here are used in multiple projects, but documented only once for better maintenance. When applying this to other projects, remember that some things such as the name, repository, or paths are a bit different.

TOC Customizations

Normal Navigation / Structure

Most of the TOCs (Table of Contents) are automatically generated by DocFX based on the structure of the markdown files. This is a bit tricky, but works as expected.

API Navigation

The TOC for the C# APIs are fairly challenging because the default only offers 2 options:

  1. Generate a deep tree structure, where every namespace behaves like a folder (nested)
  2. Generate a flat list of all namespaces

Both variants are not very user-friendly, so we've created a special script which enhances the TOC. Our Goals:

  1. Most root namespaces are "flattened" so that the initial menu has most of the namespaces visible.
  2. Important namespaces are highlighted with emojis.

This is done as follows:

  1. The script /templates/[project]/toc.json.js is run by docfx when building the API documentation. We customized it to do the following...

  2. Retrieve the build-toc-specs.js which is a project specific "database" for what we want to customized in this specific project.

  3. Run scripts inside the /templates/[project]/build-toc folder (these scripts are identical in all projects 🌴/🩸/♾️) to make the following adjustments

    1. Flatten the namespaces we think are important, so they appear in the initial menu

    2. Highlight important namespaces with emojis


Main Author

Daniel Mettler, @iJungleboy [MS MVP, Oqtane Core Team]

Content Management Expert, Chief Architect of 2sxc and cre8magic.
Forged in the jungles of Indonesia, lives in Switzerland , loves Oqtane 🩸 & 2sxc 💜.

LinkedIn | Discord: @iJungleboy | Twitter: @iJungleboy | Github: @iJungleboy

Edit this page