Skip to main content

Table of Contents

Two ways to list table of contents.

  1. List the contents within the same document.
  2. List contents for different documents. Say, an index page.

Below is auto listed TOC for this document

Full table of contents​

This is the simplest way and is autogenerated on usage of TOCInline component from docusaurus.

import TOCInline from '@theme/TOCInline';

<TOCInline toc={toc} />

Please refer docusaurus Inline TOC docs for more insights into syntax and usage of TOCInline.

Please use this CustomTOCListHead component to add custom heading like stuff for TOC.

import { CustomTOCListHead } from "@site/src/components/CustomTOCList";

<CustomTOCListHead>Table of Contents</CustomTOCListHead>
<TOCInline toc={toc} />

Will see more about this component in below sections.

info
  • The :depth: param can be controlled by toc_min_heading_level and toc_max_heading_level meta for individual files and minHeadingLevel and maxHeadingLevel for global theme config in docusaurus as given in docs.
  • The :backlinks: seems to be set to none for all and also there is no direct replacement in MDX via Docusaurus. So, can be ignored.
  • The :local can be ignored as well cause the TOCInline component works only for local (same) document
Important Note

Please ignore top-level TOC (the one at beginning of the file). Only add for sub-section TOCs. This is to avoid redundancy as TOC is available on right sidebar.

Partial (sub) table of contents​

If one individual section requires to have its own TOC. Below is how it can be achieved in docusaurus.

Changing the depth (minHeadingLevel or maxHeadingLevel) value for auto-generated TOC will not auto-generate a sub table of contents for that particular section.

  .. contents:: Table of contents
    :backlinks: none
    :depth: 1
    :local:

Good news is its doable though. Need to do this manually using filterTOC prop for the TOCInline component.

You can use the url ref id of a sub-section to display its local TOC.

To only list a sub-section list from below Table of Contents,

For this section, the url is /docs/wiki/docusaurus-mdx-guide/table-of-contents/#partial-sub-table-of-contents, hence:

// Render only the "Partial (Sub) Table of Contents" sub-items if any.
<TOCInline
  toc={toc}
  filterTOC={'partial-sub-table-of-contents'}
/>

will result in:

note

The filterTOC prop can also be a function whose return value should be an array.

filterTOC={tocTree => ([ toc[2], ... ])} or filterTOC={tocTree => toc[1].children}
filterTOC prop is not available by default - it is custom implemented

The TOCInline and TOCItems components are swizzled and custom logic is added.

The custom added logic (src/theme/TOCInline, src/theme/TOCItems) is indicated by comments - // Customization START and // Customization END. If reswizzled in future only these blocks need an update.

toc is a flat array and has no concept of nested tree children structure. This behavior is changed in 2.0.0-beta.16. Please check the Breaking changes that forced us to swizzle

Dummy section 1​

Dummy section 1.1​

Dummy section 2​

Custom table of contents​

Custom/Manually generated TOC can be a simple list or a group of lists (like a root index page)

Simple list​

Unfortunately, there is no direct alternative for this in either MDX or Docusaurus.

So, we have to rely on simple MDX links and manually find file paths, similar to how we handle refs in Links.

- [Allow Lists](/graphql/cloud/security/allow-lists.mdx)
- [API Limits](/graphql/cloud/security/api-limits.mdx)
- [Disable GraphQL Introspection](/graphql/cloud/security/disable-graphql-introspection.mdx)
- [Rotating Admin Secrets](/graphql/cloud/security/rotating-admin-secrets.mdx)

or if this needs to be done nested in a react component that doesn't support MDX.

import Link from '@docusaurus/Link';
import {
  CustomTOCList, CustomTOCListSection, CustomTOCListHead, CustomTOCListContent,
} from "@site/src/components/CustomTOCList";

<CustomTOCList>
  <CustomTOCListSection>
    <CustomTOCListContent>
      <Link to="/docs/graphql/cloud/security/allow-lists">Allow Lists</Link>
      <Link to="/docs/graphql/cloud/security/api-limits">API Limits</Link>
      <Link to="/docs/graphql/cloud/security/disable-graphql-introspection">Disable GraphQL Introspection</Link>
      <Link to="/docs/graphql/cloud/security/rotating-admin-secrets">Rotating Admin Secrets</Link>
    </CustomTOCListContent>
  </CustomTOCListSection>
</CustomTOCList>
Watchout the link type

If you notice, we have added extension to the paths in link where as in <Link /> component we didn't.

That's because, the MDX links are treated as file-paths and is resolved to generated url paths automatically by docusaurus. On the other hand, the path in Link component should already be a url path as it cannot resolve file-paths.

The best practice is to keep the directory/file path structure and url structure same to avoid the maintenance burden when using both types of syntax.

Result UI​

will render something like below.

Group of lists​

Its a list of simple lists (UI wise).

Unfortunately, there is no direct alternative for this in either MDX or Docusaurus. So we have to list these links manually using this CustomTOCList component.

  import Link from '@docusaurus/Link';
  import {
    CustomTOCList, CustomTOCListSection, CustomTOCListHead, CustomTOCListContent,
  } from "@site/src/components/CustomTOCList";

  <CustomTOCList>

    <CustomTOCListSection>

      <CustomTOCListHead>API Security</CustomTOCListHead>

      <CustomTOCListContent>
        <Link to="/root/relative/path/to/cloud-api-reference">API Limits</Link>
        <Link to="/root/relative/path/to/allow-lists">Allow Lists</Link>
      </CustomTOCListContent>

    </CustomTOCListSection>

    <CustomTOCListSection>

      <CustomTOCListHead>Reference</CustomTOCListHead>

      <CustomTOCListContent>
        <Link to="/root/relative/path/to/cloud-api-reference">Cloud API Reference</Link>
        <Link to="/root/relative/path/to/glossary">Glossary</Link>
        <Link to="/root/relative/path/to/hasurapro-cli">Hasura Pro CLI</Link>
      </CustomTOCListContent>

    </CustomTOCListSection>

  </CustomTOCList>

Result UI​

This will render something like the below. Please note that links will be broken as they are just samples.

How to use links within React?
import Link from '@docusaurus/Link';

<Link to="/wiki/docusaurus-mdx-guide/links#root-relative-links">Root Relative Links</Link>