Skip to content

Topic 7: Remove tables of contents

TO UPDATE THIS PAGE: Open and edit the topic_7.md file, in docs/ folder, to delete this placeholder text and customize with your own!

In this MkDocs template, you'll notice that a Table of Contents is automatically created on pages with headings (starting with Level 2 headers as top-level items).

To remove the automatic Table of Contents, open the mkdocs.yml file. In the theme section, adjust the toc settings to disable it.

That section in mkdocs.yml would then look like this, and the Table of Contents won't appear:

theme:
  name: 'material'
  toc:
    enabled: false

Steps to Disable the Table of Contents in MkDocs

  1. Open mkdocs.yml:

  2. Locate your mkdocs.yml configuration file in the root of your MkDocs project.

  3. Modify the Theme Section:

  4. Add or update the theme section to include the toc settings with enabled: false.

  5. Save Changes:

  6. Save the file to apply the changes.

  7. Rebuild Your Site:

  8. Run mkdocs serve to test the changes locally and ensure the Table of Contents is no longer appearing on your pages.
  9. Once satisfied, deploy your site using mkdocs gh-deploy.

Removing the Table of Contents for a single page

If you want to remove the Table of Contents (ToC) for a specific page in MkDocs, you can do this by using the md-specific metadata at the top of your Markdown file. Here’s how you can achieve this:

  1. Open the Markdown File:

  2. Locate the Markdown file for the page where you want to disable the Table of Contents.

  3. Add Metadata to Disable ToC:

  4. At the top of the Markdown file, add the following YAML front matter to disable the ToC for that page:
---
title: Page Title
description: Page description
hide:
  - toc
---

# Your Page Title

Your content goes here...
  1. Save Changes:

  2. Save the Markdown file with the added front matter.

  3. Rebuild and Test Your Site:

  4. Run mkdocs serve to view the changes locally and confirm that the ToC is not appearing on that specific page.
  5. Deploy your site using mkdocs gh-deploy once you are satisfied with the results.

How does this work?

  • YAML Front Matter: The YAML front matter (--- block) is used to set page-specific options in MkDocs. The hide: - toc setting specifically instructs MkDocs to hide the Table of Contents for that page.

To learn more about MkDocs YAML front matter and page-specific options, you can refer to the following resources:

  1. MkDocs Official Documentation:
    The MkDocs documentation provides a comprehensive guide on configuring your site, including YAML front matter options for individual pages. MkDocs Configuration

  2. MkDocs-Material Theme Documentation:
    If you are using the MkDocs-Material theme, it offers additional options and detailed explanations of YAML front matter specific to this theme. It includes various customization options like hiding elements, setting metadata, and more. MkDocs-Material Theme