graphql-engine/docs/wiki/docusaurus-mdx-guide/table-of-contents.mdx

---
sidebar_position: 5
---
import TOCInline from '@theme/TOCInline';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import Link from '@docusaurus/Link';
import { CustomTOCList, CustomTOCListSection, CustomTOCListHead, CustomTOCListContent } from "@site/src/components/CustomTOCList";

# 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.

<br />

Below is auto listed TOC for this document
<TOCInline toc={toc} />


## Full table of contents

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

```jsx
import TOCInline from '@theme/TOCInline';

<TOCInline toc={toc} />
```

Please refer docusaurus [Inline TOC docs](https://docusaurus.io/docs/markdown-features/inline-toc) for more insights into syntax and usage of `TOCInline`.

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

```jsx {1,3}
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`](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#toc_min_heading_level)
meta for individual files and [`minHeadingLevel` and `maxHeadingLevel`](https://docusaurus.io/docs/api/themes/configuration#table-of-contents)
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

:::

:::caution 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.

```rest {3}
  .. 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,

<TOCInline toc={toc} />

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

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

will result in:

<TOCInline toc={toc} filterTOC={'partial-sub-table-of-contents'} />

:::note

The `filterTOC` prop can also be a function whose return value should be an array.
```jsx
filterTOC={tocTree => ([ toc[2], ... ])} or filterTOC={tocTree => toc[1].children}
```

:::

:::danger `filterTOC` prop is not available by default - it is custom implemented

The `TOCInline` and `TOCItems` components are [swizzled](https://docusaurus.io/docs/swizzling) 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](https://docusaurus.io/docs/markdown-features/inline-toc#custom-table-of-contents) 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](https://docusaurus.io/changelog/2.0.0-beta.16#-breaking-change)

:::

### 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](/docusaurus-mdx-guide/links.mdx#internal-links).

```markdown
- [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.

```jsx
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>
```

:::caution 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.

```jsx
  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.

<CustomTOCList>
  <CustomTOCListSection>
    <CustomTOCListHead>API Security</CustomTOCListHead>
    <CustomTOCListContent>
      <Link to="#cloud-api-reference">API Limits</Link>
      <Link to="#allow-lists">Allow Lists</Link>
    </CustomTOCListContent>
  </CustomTOCListSection>
  <CustomTOCListSection>
    <CustomTOCListHead>Reference</CustomTOCListHead>
    <CustomTOCListContent>
      <Link to="#cloud-api-reference">Cloud API Reference</Link>
      <Link to="#glossary">Glossary</Link>
      <Link to="#hasurapro-cli">Hasura Pro CLI</Link>
    </CustomTOCListContent>
  </CustomTOCListSection>
</CustomTOCList>

<hr />

:::tip How to use links within React?

- Please refer to the [Links in React](/docusaurus-mdx-guide/links.mdx#links-in-react) section in Links.

```jsx
import Link from '@docusaurus/Link';

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

- Please refer to the [Root Relative Links](/wiki/docusaurus-mdx-guide/links#root-relative-links) section too.

:::