Table of Contents in DocFx

DocFx uses YAML files called toc.yml for the table of contents. Typically these will be small files located in various folders, which define the structure of the documentation. Here's an example:

- name: Introduction
  href: index.md
  items:
  - name: What is 2sxc
    href: what-is-2sxc.md
  - name: Why 2sxc
    href: why-2sxc.md

There are a few important things to know:

Sections in the Table of Contents

Each entry looks a bit like this:

- name: Introduction
  thing1: someValue
  thing2: anotherValue
  thing3: yetAnotherValue
  items:
  - name: This is a Sub Section
    href: sub-section.md
  - name: This is another Sub Section
    href: another-sub-section.md

As you can see, it expects a - name prefixed by a dash + space. The following lines which belong to this name must be indented by 2 spaces.

Tip

YAML uses indentation to define the structure.

The items key is a special key which contains a list of sub-sections. Anything below that is again indented. Note that we rarely use items, since we usually just reference other TOC files (explained below).

Linking to Files & Websites

Typically we'll reference another file like this:

- name: Introduction
  href: index.md
- name: What is 2sxc
  href: what-is-2sxc.md
- name: Something in a subfolder
  href: subfolder/some-file.md
- name: Something in a parent folder
  href: ../some-file.md

You can also create links to external websites like this:

- name: Introduction
  href: https://www.2sxc.org

Linking with Permalinks (UIDs)

For more robust linking we usually use UIDs. In this scenario, pages have a small header like this:

---
uid: Abyss.Contribute.Docs.Edit.Toc
---

The toc.yml can then reference it like this:

- name: Edit Table of Contents
  uid: Abyss.Contribute.Docs.Edit.Toc

Tip

This is very powerful because it allows us to move pages around without breaking links.

So for extensive documentations, we always use UIDs.

Linking to Namespaces and Objects

The same UID concept applies to namespaces and objects. Their UIDs are automatically generated by DocFx, and match the full namespaces of the C# objects.

- name: Namespace
  uid: ToSic.Eav.Data
- name: Class
  uid: ToSic.Eav.Data.IEntity
- name: Property
  uid: ToSic.Eav.Data.IEntity.Title

Adding a few Sub-Nodes in the TOC

If you want to add a few sub-nodes to a TOC, you can

add them directly below items
reference another TOC file

Here's how you would add a few sub-nodes directly, which open when the Introduction page is visited:

- name: Introduction
  href: index.md
  items:
  - name: What is 2sxc
    href: what-is-2sxc.md
  - name: Why 2sxc
    href: why-2sxc.md

You can also do the same without a real Introduction page, so that the Introduction title is shown, but clicking it will only unfold the menu:

- name: Introduction
  items:
  - name: What is 2sxc
    href: what-is-2sxc.md
  - name: Why 2sxc
    href: why-2sxc.md

If you want to reference another TOC file, continue below...

Structuring - Loose vs. Tight

The TOC can be structured in a loose or tight way.

Loose Structure

The loose way assumes that there is no real hierarchy, and that the TOC is just a list of links. When docfx shows a page, it will find all toc.yml files which reference it and pick "the best" TOC to show. In this scenario, there is no overall structure. To explain this, let's assume we have 3 files:

The root toc.yml which links to various pages including the /abyss/index.md

- name: Home
  href: index.md
- name: Abyss
  href: abyss/index.md
- name: Guides
  items:
  - name: Guide 1
    href: guide1.md
  - name: Guide 2
    href: guide2.md

The abyss/toc.yml which also links the /abyss/index.md

- name: Abyss
  href: index.md
- name: Something in the Abyss
  href: something.md

The /abyss/index.md file not shown here.

The resulting output will do this:

When the user is on the root, he will see the Home and Abyss links. These will not have sub-links!

- Home
- Abyss     # note: no (+) to unfold
+ Guides    # note: (+) to unfold as it's a true hierarchy

When the user is on the /abyss/index.md page, the initial TOC will not be shown any more, as it's not relevant. The TOC will now show the Abyss TOC, which will show the Abyss link
```
- Abyss
- Something in the Abyss
```

Tip

We call this loosely structured, because the TOCs don't really have a hierarchy.

Tip

This is not the recommended way for most scenarios, but there are cases where this is a good choice. An example is the main menu, where we don't want to have dropdowns for every sub-item.

Tight Structure

The tight way assumes that there is a clear hierarchy, and that the TOC is a tree. In this scenario, the root toc.yml will reference all sub-TOCs, and each sub-TOC will reference its sub-TOCs. To explain this, let's assume we have 3 files:

The root toc.yml which links to the /abyss/toc.yml

- name: Home
  href: index.md
- name: Abyss
  href: abyss/toc.yml

The abyss/toc.yml which links the /abyss/index.md

- name: Abyss
  href: index.md
- name: Something in the Abyss
  href: something.md

The /abyss/index.md file not shown here.

The resulting output will do this:

When the user is on the root, he will see the Home and Abyss links. These will have sub-links!
```
- Home
+ Abyss   # note: (+) to unfold
```
When the user is on the /abyss/index.md page, the initial TOC will still be shown. The TOC will now also show the Abyss TOC, which will show the Abyss link.
```
- Home
+ Abyss   # note: (+) to unfold
  - Abyss
  - Something in the Abyss
```

Combine href and uid

You can combine href and uid like this:

- name: Abyss
  uid: Abyss.Contribute.Docs.Edit.Toc
  href: abyss/toc.yml

This makes the word Abyss be a link to Abyss.Contribute.Docs.Edit.Toc, and also connects the hierarchy. So the output & behavior will be:

+ Abyss   # note: (+) to unfold

You can now click on the Abyss link to go to the Abyss.Contribute.Docs.Edit.Toc page. You can also click on the + to unfold the Abyss TOC.

Tip

This is usually our recommended way to structure the TOC.

It allows you to make the parent-node the "overview" page, and the child-nodes the details.

Edge Cases

Combine href for link and href for sub-TOC

In a rare case you may have a TOC which is both a non-UID link and a sub-TOC.

- name: Abyss
  href: abyss/toc.yml
  topicHref: something.md

Table of Contents