TOC Configuration
3
2
Markdown Table of Contents Guide
Learn how to create and use tables of contents in your markdown documents to improve navigation and readability.
What is a Table of Contents?
A table of contents (TOC) is a list of links that point to different sections within your document. In markdown, these sections are defined by headings (lines that start with # symbols). A well-structured TOC helps readers navigate your document and understand its organization at a glance.
A basic table of contents with links to different sections of a document.
# Table of Contents
- [Introduction](#introduction)
- [Background](#background)
- [Purpose](#purpose)
- [Main Content](#main-content)
- [Section One](#section-one)
- [Section Two](#section-two)
- [Conclusion](#conclusion)Benefits of Using a TOC
- Improves navigation in long documents
- Provides a quick overview of document structure
- Makes it easier for readers to find specific information
- Enhances the professional appearance of your documentation
- Helps maintain a logical document structure
How Markdown TOC Links Work
Markdown TOC links work by creating anchors to headings in your document. When a user clicks on a TOC link, they're taken directly to that section. The link format varies slightly between platforms:
Different platforms may use different link formats for heading anchors.
## My Section Title
[Link to section](#my-section-title) <!-- GitHub/GitLab style -->
[Link to section](#markdown-header-my-section-title) <!-- Bitbucket style -->The anchor is typically created by converting the heading text to lowercase, replacing spaces with hyphens, and removing special characters. Our TOC generator handles these conversions automatically based on your selected platform.
Advanced TOC Features
Collapsible TOC
For very long documents, you can make your TOC collapsible using HTML details/summary tags:
A collapsible TOC that can be expanded or collapsed by clicking.
<details>
<summary>Table of Contents</summary>
- [Section 1](#section-1)
- [Section 2](#section-2)
- [Subsection 2.1](#subsection-21)
- [Subsection 2.2](#subsection-22)
- [Section 3](#section-3)
</details>Numbered TOC
You can use numbered lists for a more structured TOC:
A numbered TOC that shows the hierarchical structure more explicitly.
# Table of Contents
1. [Introduction](#introduction)
1.1. [Background](#background)
1.2. [Purpose](#purpose)
2. [Main Content](#main-content)
2.1. [Section One](#section-one)
2.2. [Section Two](#section-two)
3. [Conclusion](#conclusion)Frequently Asked Questions
Why doesn't my TOC link work?
TOC links may not work if there's a mismatch between the link format and the platform you're using. Make sure to select the correct link style (GitHub, GitLab, Bitbucket, or Notion) in our generator.
How deep should my TOC go?
For most documents, including headings up to level 3 (###) provides a good balance between detail and readability. Very long or complex documents might benefit from deeper levels.
Should I include the document title in the TOC?
It's generally best to skip the first heading (document title) in your TOC, as it's redundant. Our generator includes an option to automatically skip the first heading.
Can I customize the TOC appearance?
Yes, you can customize bullet styles, indentation, and other formatting options. Some platforms also support custom CSS that can be applied to your TOC for additional styling.
Why Use a Markdown TOC Generator?
While you can create a table of contents manually, it's time-consuming and error-prone, especially for longer documents or when you make changes to your headings. Our TOC generator automatically creates properly formatted links, handles special characters, and ensures consistent formatting. It saves you time and helps maintain accurate navigation as your document evolves.
Got Feedback? 📢