[{"data":1,"prerenderedAt":77},["Reactive",2],{"blog-post-how-to-create-table-of-contents-in-markdown":3},{"slug":4,"title":5,"description":6,"excerpt":7,"date":8,"category":9,"author":10,"keywords":11,"readingMinutes":12,"html":13,"headings":14,"tools":49,"related":54},"how-to-create-table-of-contents-in-markdown","How to Create a Table of Contents in Markdown: Complete Guide","Learn how to create and customize table of contents in Markdown using automatic generation, manual methods, and platform-specific solutions. Includes examples for GitHub, Jekyll, and more.","Creating a table of contents (TOC) in Markdown helps readers navigate long documents efficiently. While standard Markdown doesn't include built-in TOC functionality, there are several effective…","2025-08-08","Tutorial","Matthew Rathbone","table of contents markdown, markdown toc, automatic table of contents markdown, markdown navigation, github table of contents",5,"\u003Cp>Creating a table of contents (TOC) in Markdown helps readers navigate long documents efficiently. While standard Markdown doesn't include built-in TOC functionality, there are several effective methods to generate navigation menus for your documents. This comprehensive guide covers automatic generation, manual creation, and platform-specific solutions.\u003C/p>\n\u003Ch2 id=\"why-add-a-table-of-contents\">Why Add a Table of Contents?\u003C/h2>\n\u003Cp>A well-structured table of contents provides several benefits:\u003C/p>\n\u003Cul>\n\u003Cli>\u003Cstrong>Improved Navigation\u003C/strong>: Readers can quickly jump to relevant sections\u003C/li>\n\u003Cli>\u003Cstrong>Better User Experience\u003C/strong>: Especially valuable for long-form content and documentation\u003C/li>\n\u003Cli>\u003Cstrong>SEO Benefits\u003C/strong>: Search engines can better understand document structure\u003C/li>\n\u003Cli>\u003Cstrong>Professional Appearance\u003C/strong>: Makes documents look more organized and complete\u003C/li>\n\u003C/ul>\n\u003Ch2 id=\"method-1-automatic-toc-generation\">Method 1: Automatic TOC Generation\u003C/h2>\n\u003Cp>Many Markdown processors and static site generators can automatically generate table of contents from your document headings.\u003C/p>\n\u003Ch3 id=\"github-flavored-markdown\">GitHub-Flavored Markdown\u003C/h3>\n\u003Cp>GitHub automatically generates a TOC for files in repositories. You can access it by clicking the "table of contents" icon in the file header, but you cannot embed it directly in the document.\u003C/p>\n\u003Ch3 id=\"jekyll-and-github-pages\">Jekyll and GitHub Pages\u003C/h3>\n\u003Cp>Jekyll sites can use plugins to automatically generate TOCs:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-yaml\">\u003Cspan class=\"hljs-comment\"># In _config.yml\u003C/span>\n\u003Cspan class=\"hljs-attr\">plugins:\u003C/span>\n  \u003Cspan class=\"hljs-bullet\">-\u003C/span> \u003Cspan class=\"hljs-string\">jekyll-toc\u003C/span>\n\u003C/code>\u003C/pre>\u003Cp>Then add this to your layout or post:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-liquid\">{{ content | toc }}\n\u003C/code>\u003C/pre>\u003Ch3 id=\"using-pandoc\">Using Pandoc\u003C/h3>\n\u003Cp>Pandoc can generate a TOC when converting documents:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-bash\">pandoc --toc --toc-depth=3 document.md -o output.html\n\u003C/code>\u003C/pre>\u003Ch2 id=\"method-2-manual-table-of-contents\">Method 2: Manual Table of Contents\u003C/h2>\n\u003Cp>Creating a manual TOC gives you complete control over structure and appearance.\u003C/p>\n\u003Ch3 id=\"basic-manual-toc-structure\">Basic Manual TOC Structure\u003C/h3>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">\u003Cspan class=\"hljs-section\">## Table of Contents\u003C/span>\n\n\u003Cspan class=\"hljs-bullet\">1.\u003C/span> [\u003Cspan class=\"hljs-string\">Introduction\u003C/span>](\u003Cspan class=\"hljs-link\">#introduction\u003C/span>)\n\u003Cspan class=\"hljs-bullet\">2.\u003C/span> [\u003Cspan class=\"hljs-string\">Getting Started\u003C/span>](\u003Cspan class=\"hljs-link\">#getting-started\u003C/span>)\n\u003Cspan class=\"hljs-bullet\">   -\u003C/span> [\u003Cspan class=\"hljs-string\">Prerequisites\u003C/span>](\u003Cspan class=\"hljs-link\">#prerequisites\u003C/span>)\n\u003Cspan class=\"hljs-bullet\">   -\u003C/span> [\u003Cspan class=\"hljs-string\">Installation\u003C/span>](\u003Cspan class=\"hljs-link\">#installation\u003C/span>)\n\u003Cspan class=\"hljs-bullet\">3.\u003C/span> [\u003Cspan class=\"hljs-string\">Usage Examples\u003C/span>](\u003Cspan class=\"hljs-link\">#usage-examples\u003C/span>)\n\u003Cspan class=\"hljs-bullet\">4.\u003C/span> [\u003Cspan class=\"hljs-string\">Advanced Features\u003C/span>](\u003Cspan class=\"hljs-link\">#advanced-features\u003C/span>)\n\u003Cspan class=\"hljs-bullet\">5.\u003C/span> [\u003Cspan class=\"hljs-string\">Troubleshooting\u003C/span>](\u003Cspan class=\"hljs-link\">#troubleshooting\u003C/span>)\n\u003Cspan class=\"hljs-bullet\">6.\u003C/span> [\u003Cspan class=\"hljs-string\">Conclusion\u003C/span>](\u003Cspan class=\"hljs-link\">#conclusion\u003C/span>)\n\u003C/code>\u003C/pre>\u003Ch3 id=\"creating-anchor-links\">Creating Anchor Links\u003C/h3>\n\u003Cp>Markdown automatically creates anchor links from headings. The anchor is typically the heading text in lowercase with spaces replaced by hyphens:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">\u003Cspan class=\"hljs-section\"># Getting Started\u003C/span>\n\u003Cspan class=\"hljs-section\">## User Authentication\u003C/span>\n\u003Cspan class=\"hljs-section\">### OAuth Setup\u003C/span>\n\n<!-- Links to these sections -->\n[\u003Cspan class=\"hljs-string\">Getting Started\u003C/span>](\u003Cspan class=\"hljs-link\">#getting-started\u003C/span>)\n[\u003Cspan class=\"hljs-string\">User Authentication\u003C/span>](\u003Cspan class=\"hljs-link\">#user-authentication\u003C/span>)\n[\u003Cspan class=\"hljs-string\">OAuth Setup\u003C/span>](\u003Cspan class=\"hljs-link\">#oauth-setup\u003C/span>)\n\u003C/code>\u003C/pre>\u003Ch3 id=\"handling-special-characters-in-headings\">Handling Special Characters in Headings\u003C/h3>\n\u003Cp>For headings with special characters, the anchor generation varies by platform:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">\u003Cspan class=\"hljs-section\"># API & SDK Setup\u003C/span>\n<!-- GitHub link: #api--sdk-setup -->\n<!-- Other platforms may vary -->\n\n\u003Cspan class=\"hljs-section\"># Cost ($) Analysis\u003C/span>\n<!-- GitHub link: #cost--analysis -->\n\u003C/code>\u003C/pre>\u003Ch2 id=\"method-3-javascript-based-toc-generation\">Method 3: JavaScript-Based TOC Generation\u003C/h2>\n\u003Cp>For web-based Markdown rendering, JavaScript can dynamically create table of contents.\u003C/p>\n\u003Ch3 id=\"simple-javascript-toc\">Simple JavaScript TOC\u003C/h3>\n\u003Cpre>\u003Ccode class=\"hljs language-javascript\">\u003Cspan class=\"hljs-keyword\">function\u003C/span> \u003Cspan class=\"hljs-title function_\">generateTOC\u003C/span>(\u003Cspan class=\"hljs-params\">\u003C/span>) {\n  \u003Cspan class=\"hljs-keyword\">const\u003C/span> headings = \u003Cspan class=\"hljs-variable language_\">document\u003C/span>.\u003Cspan class=\"hljs-title function_\">querySelectorAll\u003C/span>(\u003Cspan class=\"hljs-string\">'h1, h2, h3, h4, h5, h6'\u003C/span>);\n  \u003Cspan class=\"hljs-keyword\">const\u003C/span> toc = \u003Cspan class=\"hljs-variable language_\">document\u003C/span>.\u003Cspan class=\"hljs-title function_\">getElementById\u003C/span>(\u003Cspan class=\"hljs-string\">'table-of-contents'\u003C/span>);\n  \n  \u003Cspan class=\"hljs-keyword\">let\u003C/span> tocHTML = \u003Cspan class=\"hljs-string\">'<ul>'\u003C/span>;\n  \n  headings.\u003Cspan class=\"hljs-title function_\">forEach\u003C/span>(\u003Cspan class=\"hljs-function\">(\u003Cspan class=\"hljs-params\">heading, index\u003C/span>) =>\u003C/span> {\n    \u003Cspan class=\"hljs-keyword\">const\u003C/span> id = heading.\u003Cspan class=\"hljs-property\">id\u003C/span> || \u003Cspan class=\"hljs-string\">`heading-\u003Cspan class=\"hljs-subst\">${index}\u003C/span>`\u003C/span>;\n    heading.\u003Cspan class=\"hljs-property\">id\u003C/span> = id;\n    \n    \u003Cspan class=\"hljs-keyword\">const\u003C/span> level = \u003Cspan class=\"hljs-built_in\">parseInt\u003C/span>(heading.\u003Cspan class=\"hljs-property\">tagName\u003C/span>.\u003Cspan class=\"hljs-title function_\">charAt\u003C/span>(\u003Cspan class=\"hljs-number\">1\u003C/span>));\n    \u003Cspan class=\"hljs-keyword\">const\u003C/span> indent = \u003Cspan class=\"hljs-string\">'  '\u003C/span>.\u003Cspan class=\"hljs-title function_\">repeat\u003C/span>(level - \u003Cspan class=\"hljs-number\">1\u003C/span>);\n    \n    tocHTML += \u003Cspan class=\"hljs-string\">`\u003Cspan class=\"hljs-subst\">${indent}\u003C/span><li><a href="#\u003Cspan class=\"hljs-subst\">${id}\u003C/span>">\u003Cspan class=\"hljs-subst\">${heading.textContent}\u003C/span></a></li>`\u003C/span>;\n  });\n  \n  tocHTML += \u003Cspan class=\"hljs-string\">'</ul>'\u003C/span>;\n  toc.\u003Cspan class=\"hljs-property\">innerHTML\u003C/span> = tocHTML;\n}\n\u003C/code>\u003C/pre>\u003Cp>This approach is covered in detail in our guide on \u003Ca href=\"/blog/add-table-of-contents-to-markdown-using-javascript\">adding table of contents to markdown using JavaScript\u003C/a>.\u003C/p>\n\u003Ch2 id=\"method-4-platform-specific-solutions\">Method 4: Platform-Specific Solutions\u003C/h2>\n\u003Ch3 id=\"gitbook\">GitBook\u003C/h3>\n\u003Cp>GitBook automatically generates TOCs from your document structure:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">\u003Cspan class=\"hljs-section\"># Table of contents\u003C/span>\n\n\u003Cspan class=\"hljs-bullet\">*\u003C/span> [\u003Cspan class=\"hljs-string\">Introduction\u003C/span>](\u003Cspan class=\"hljs-link\">README.md\u003C/span>)\n\u003Cspan class=\"hljs-bullet\">*\u003C/span> [\u003Cspan class=\"hljs-string\">Chapter 1\u003C/span>](\u003Cspan class=\"hljs-link\">chapter1.md\u003C/span>)\n\u003Cspan class=\"hljs-bullet\">*\u003C/span> [\u003Cspan class=\"hljs-string\">Chapter 2\u003C/span>](\u003Cspan class=\"hljs-link\">chapter2.md\u003C/span>)\n\u003Cspan class=\"hljs-bullet\">  *\u003C/span> [\u003Cspan class=\"hljs-string\">Section 2.1\u003C/span>](\u003Cspan class=\"hljs-link\">chapter2/section1.md\u003C/span>)\n\u003Cspan class=\"hljs-bullet\">  *\u003C/span> [\u003Cspan class=\"hljs-string\">Section 2.2\u003C/span>](\u003Cspan class=\"hljs-link\">chapter2/section2.md\u003C/span>)\n\u003C/code>\u003C/pre>\u003Ch3 id=\"notion\">Notion\u003C/h3>\n\u003Cp>Notion provides a \u003Ccode>/table\u003C/code> command that creates an automatic TOC based on page headings.\u003C/p>\n\u003Ch3 id=\"mkdocs\">MkDocs\u003C/h3>\n\u003Cp>MkDocs generates navigation automatically from your \u003Ccode>mkdocs.yml\u003C/code> configuration:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-yaml\">\u003Cspan class=\"hljs-attr\">nav:\u003C/span>\n  \u003Cspan class=\"hljs-bullet\">-\u003C/span> \u003Cspan class=\"hljs-attr\">Home:\u003C/span> \u003Cspan class=\"hljs-string\">index.md\u003C/span>\n  \u003Cspan class=\"hljs-bullet\">-\u003C/span> \u003Cspan class=\"hljs-attr\">User Guide:\u003C/span>\n    \u003Cspan class=\"hljs-bullet\">-\u003C/span> \u003Cspan class=\"hljs-attr\">Installation:\u003C/span> \u003Cspan class=\"hljs-string\">installation.md\u003C/span>\n    \u003Cspan class=\"hljs-bullet\">-\u003C/span> \u003Cspan class=\"hljs-attr\">Configuration:\u003C/span> \u003Cspan class=\"hljs-string\">configuration.md\u003C/span>\n  \u003Cspan class=\"hljs-bullet\">-\u003C/span> \u003Cspan class=\"hljs-attr\">API Reference:\u003C/span> \u003Cspan class=\"hljs-string\">api.md\u003C/span>\n\u003C/code>\u003C/pre>\u003Ch3 id=\"hugo\">Hugo\u003C/h3>\n\u003Cp>Hugo can generate TOCs using built-in variables:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-go-html-template\">{{ .TableOfContents }}\n\u003C/code>\u003C/pre>\u003Ch2 id=\"customizing-toc-appearance\">Customizing TOC Appearance\u003C/h2>\n\u003Ch3 id=\"css-styling\">CSS Styling\u003C/h3>\n\u003Cpre>\u003Ccode class=\"hljs language-css\">\u003Cspan class=\"hljs-selector-class\">.table-of-contents\u003C/span> {\n  \u003Cspan class=\"hljs-attribute\">border\u003C/span>: \u003Cspan class=\"hljs-number\">1px\u003C/span> solid \u003Cspan class=\"hljs-number\">#ddd\u003C/span>;\n  \u003Cspan class=\"hljs-attribute\">border-radius\u003C/span>: \u003Cspan class=\"hljs-number\">5px\u003C/span>;\n  \u003Cspan class=\"hljs-attribute\">padding\u003C/span>: \u003Cspan class=\"hljs-number\">20px\u003C/span>;\n  \u003Cspan class=\"hljs-attribute\">margin\u003C/span>: \u003Cspan class=\"hljs-number\">20px\u003C/span> \u003Cspan class=\"hljs-number\">0\u003C/span>;\n  \u003Cspan class=\"hljs-attribute\">background-color\u003C/span>: \u003Cspan class=\"hljs-number\">#f9f9f9\u003C/span>;\n}\n\n\u003Cspan class=\"hljs-selector-class\">.table-of-contents\u003C/span> \u003Cspan class=\"hljs-selector-tag\">ul\u003C/span> {\n  \u003Cspan class=\"hljs-attribute\">list-style-type\u003C/span>: none;\n  \u003Cspan class=\"hljs-attribute\">padding-left\u003C/span>: \u003Cspan class=\"hljs-number\">0\u003C/span>;\n}\n\n\u003Cspan class=\"hljs-selector-class\">.table-of-contents\u003C/span> \u003Cspan class=\"hljs-selector-tag\">li\u003C/span> {\n  \u003Cspan class=\"hljs-attribute\">padding\u003C/span>: \u003Cspan class=\"hljs-number\">5px\u003C/span> \u003Cspan class=\"hljs-number\">0\u003C/span>;\n}\n\n\u003Cspan class=\"hljs-selector-class\">.table-of-contents\u003C/span> \u003Cspan class=\"hljs-selector-tag\">a\u003C/span> {\n  \u003Cspan class=\"hljs-attribute\">text-decoration\u003C/span>: none;\n  \u003Cspan class=\"hljs-attribute\">color\u003C/span>: \u003Cspan class=\"hljs-number\">#333\u003C/span>;\n}\n\n\u003Cspan class=\"hljs-selector-class\">.table-of-contents\u003C/span> \u003Cspan class=\"hljs-selector-tag\">a\u003C/span>\u003Cspan class=\"hljs-selector-pseudo\">:hover\u003C/span> {\n  \u003Cspan class=\"hljs-attribute\">text-decoration\u003C/span>: underline;\n  \u003Cspan class=\"hljs-attribute\">color\u003C/span>: \u003Cspan class=\"hljs-number\">#007cba\u003C/span>;\n}\n\u003C/code>\u003C/pre>\u003Ch3 id=\"multi-level-indentation\">Multi-Level Indentation\u003C/h3>\n\u003Cp>For nested TOCs, use proper indentation:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">\u003Cspan class=\"hljs-section\">## Table of Contents\u003C/span>\n\n\u003Cspan class=\"hljs-bullet\">-\u003C/span> [\u003Cspan class=\"hljs-string\">Chapter 1\u003C/span>](\u003Cspan class=\"hljs-link\">#chapter-1\u003C/span>)\n\u003Cspan class=\"hljs-bullet\">  -\u003C/span> [\u003Cspan class=\"hljs-string\">Section 1.1\u003C/span>](\u003Cspan class=\"hljs-link\">#section-11\u003C/span>)\n\u003Cspan class=\"hljs-bullet\">    -\u003C/span> [\u003Cspan class=\"hljs-string\">Subsection 1.1.1\u003C/span>](\u003Cspan class=\"hljs-link\">#subsection-111\u003C/span>)\n\u003Cspan class=\"hljs-bullet\">  -\u003C/span> [\u003Cspan class=\"hljs-string\">Section 1.2\u003C/span>](\u003Cspan class=\"hljs-link\">#section-12\u003C/span>)\n\u003Cspan class=\"hljs-bullet\">-\u003C/span> [\u003Cspan class=\"hljs-string\">Chapter 2\u003C/span>](\u003Cspan class=\"hljs-link\">#chapter-2\u003C/span>)\n\u003Cspan class=\"hljs-bullet\">  -\u003C/span> [\u003Cspan class=\"hljs-string\">Section 2.1\u003C/span>](\u003Cspan class=\"hljs-link\">#section-21\u003C/span>)\n\u003Cspan class=\"hljs-bullet\">  -\u003C/span> [\u003Cspan class=\"hljs-string\">Section 2.2\u003C/span>](\u003Cspan class=\"hljs-link\">#section-22\u003C/span>)\n\u003C/code>\u003C/pre>\u003Ch2 id=\"best-practices-for-toc-creation\">Best Practices for TOC Creation\u003C/h2>\n\u003Ch3 id=\"structure-guidelines\">Structure Guidelines\u003C/h3>\n\u003Col>\n\u003Cli>\u003Cstrong>Limit Depth\u003C/strong>: Typically include only H1-H3 headings for readability\u003C/li>\n\u003Cli>\u003Cstrong>Consistent Naming\u003C/strong>: Use descriptive, consistent heading names\u003C/li>\n\u003Cli>\u003Cstrong>Logical Order\u003C/strong>: Organize sections in a logical, progressive manner\u003C/li>\n\u003Cli>\u003Cstrong>Regular Updates\u003C/strong>: Keep TOC synchronized with document changes\u003C/li>\n\u003C/ol>\n\u003Ch3 id=\"accessibility-considerations\">Accessibility Considerations\u003C/h3>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">\u003Cspan class=\"hljs-section\">## Table of Contents {#table-of-contents}\u003C/span>\n\n\u003Cspan class=\"language-xml\">\u003Cspan class=\"hljs-tag\"><\u003Cspan class=\"hljs-name\">nav\u003C/span> \u003Cspan class=\"hljs-attr\">role\u003C/span>=\u003Cspan class=\"hljs-string\">"navigation"\u003C/span> \u003Cspan class=\"hljs-attr\">aria-labelledby\u003C/span>=\u003Cspan class=\"hljs-string\">"table-of-contents"\u003C/span>>\u003C/span>\u003C/span>\n\n\u003Cspan class=\"hljs-bullet\">1.\u003C/span> [\u003Cspan class=\"hljs-string\">Introduction\u003C/span>](\u003Cspan class=\"hljs-link\">#introduction\u003C/span>)\n\u003Cspan class=\"hljs-bullet\">2.\u003C/span> [\u003Cspan class=\"hljs-string\">Getting Started\u003C/span>](\u003Cspan class=\"hljs-link\">#getting-started\u003C/span>)\n\u003Cspan class=\"hljs-bullet\">3.\u003C/span> [\u003Cspan class=\"hljs-string\">Advanced Topics\u003C/span>](\u003Cspan class=\"hljs-link\">#advanced-topics\u003C/span>)\n\n\u003Cspan class=\"language-xml\">\u003Cspan class=\"hljs-tag\"></\u003Cspan class=\"hljs-name\">nav\u003C/span>>\u003C/span>\u003C/span>\n\u003C/code>\u003C/pre>\u003Ch3 id=\"seo-optimization\">SEO Optimization\u003C/h3>\n\u003Cul>\n\u003Cli>Use descriptive anchor text\u003C/li>\n\u003Cli>Include relevant keywords in headings\u003C/li>\n\u003Cli>Maintain proper heading hierarchy (H1 → H2 → H3)\u003C/li>\n\u003Cli>Ensure links work correctly across different platforms\u003C/li>\n\u003C/ul>\n\u003Ch2 id=\"troubleshooting-common-issues\">Troubleshooting Common Issues\u003C/h2>\n\u003Ch3 id=\"links-not-working\">Links Not Working\u003C/h3>\n\u003Cp>\u003Cstrong>Problem\u003C/strong>: TOC links don't navigate to correct sections\u003C/p>\n\u003Cp>\u003Cstrong>Solutions\u003C/strong>:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\"><!-- Ensure heading IDs match links -->\n\u003Cspan class=\"hljs-section\"># Getting Started {#getting-started}\u003C/span>\n[\u003Cspan class=\"hljs-string\">Getting Started\u003C/span>](\u003Cspan class=\"hljs-link\">#getting-started\u003C/span>)\n\n<!-- Check for special character handling -->\n\u003Cspan class=\"hljs-section\"># API & Documentation\u003C/span>\n[\u003Cspan class=\"hljs-string\">API & Documentation\u003C/span>](\u003Cspan class=\"hljs-link\">#api--documentation\u003C/span>)\n\u003C/code>\u003C/pre>\u003Ch3 id=\"formatting-issues\">Formatting Issues\u003C/h3>\n\u003Cp>\u003Cstrong>Problem\u003C/strong>: TOC appears as plain text instead of links\u003C/p>\n\u003Cp>\u003Cstrong>Solutions\u003C/strong>:\u003C/p>\n\u003Cul>\n\u003Cli>Verify Markdown processor supports linking\u003C/li>\n\u003Cli>Check that headings have proper anchor generation\u003C/li>\n\u003Cli>Ensure consistent spacing and formatting\u003C/li>\n\u003C/ul>\n\u003Ch3 id=\"platform-differences\">Platform Differences\u003C/h3>\n\u003Cp>Different platforms handle anchor generation differently:\u003C/p>\n\u003Cul>\n\u003Cli>\u003Cstrong>GitHub\u003C/strong>: Converts spaces to hyphens, removes special characters\u003C/li>\n\u003Cli>\u003Cstrong>GitLab\u003C/strong>: Similar to GitHub with slight variations\u003C/li>\n\u003Cli>\u003Cstrong>Reddit\u003C/strong>: Limited TOC support\u003C/li>\n\u003Cli>\u003Cstrong>Jekyll\u003C/strong>: Configurable through plugins\u003C/li>\n\u003C/ul>\n\u003Ch2 id=\"advanced-toc-techniques\">Advanced TOC Techniques\u003C/h2>\n\u003Ch3 id=\"conditional-tocs\">Conditional TOCs\u003C/h3>\n\u003Cpre>\u003Ccode class=\"hljs language-liquid\">{% if page.toc %}\n  {% include toc.html %}\n{% endif %}\n\u003C/code>\u003C/pre>\u003Ch3 id=\"floating-toc\">Floating TOC\u003C/h3>\n\u003Cpre>\u003Ccode class=\"hljs language-css\">\u003Cspan class=\"hljs-selector-class\">.floating-toc\u003C/span> {\n  \u003Cspan class=\"hljs-attribute\">position\u003C/span>: fixed;\n  \u003Cspan class=\"hljs-attribute\">top\u003C/span>: \u003Cspan class=\"hljs-number\">20px\u003C/span>;\n  \u003Cspan class=\"hljs-attribute\">right\u003C/span>: \u003Cspan class=\"hljs-number\">20px\u003C/span>;\n  \u003Cspan class=\"hljs-attribute\">max-width\u003C/span>: \u003Cspan class=\"hljs-number\">250px\u003C/span>;\n  \u003Cspan class=\"hljs-attribute\">background\u003C/span>: white;\n  \u003Cspan class=\"hljs-attribute\">border\u003C/span>: \u003Cspan class=\"hljs-number\">1px\u003C/span> solid \u003Cspan class=\"hljs-number\">#ccc\u003C/span>;\n  \u003Cspan class=\"hljs-attribute\">border-radius\u003C/span>: \u003Cspan class=\"hljs-number\">5px\u003C/span>;\n  \u003Cspan class=\"hljs-attribute\">padding\u003C/span>: \u003Cspan class=\"hljs-number\">15px\u003C/span>;\n  \u003Cspan class=\"hljs-attribute\">box-shadow\u003C/span>: \u003Cspan class=\"hljs-number\">0\u003C/span> \u003Cspan class=\"hljs-number\">2px\u003C/span> \u003Cspan class=\"hljs-number\">10px\u003C/span> \u003Cspan class=\"hljs-built_in\">rgba\u003C/span>(\u003Cspan class=\"hljs-number\">0\u003C/span>,\u003Cspan class=\"hljs-number\">0\u003C/span>,\u003Cspan class=\"hljs-number\">0\u003C/span>,\u003Cspan class=\"hljs-number\">0.1\u003C/span>);\n}\n\u003C/code>\u003C/pre>\u003Ch3 id=\"collapsible-toc\">Collapsible TOC\u003C/h3>\n\u003Cpre>\u003Ccode class=\"hljs language-html\">\u003Cspan class=\"hljs-tag\"><\u003Cspan class=\"hljs-name\">details\u003C/span>>\u003C/span>\n\u003Cspan class=\"hljs-tag\"><\u003Cspan class=\"hljs-name\">summary\u003C/span>>\u003C/span>Table of Contents\u003Cspan class=\"hljs-tag\"></\u003Cspan class=\"hljs-name\">summary\u003C/span>>\u003C/span>\n\n1. [Introduction](#introduction)\n2. [Getting Started](#getting-started)\n3. [Advanced Topics](#advanced-topics)\n\n\u003Cspan class=\"hljs-tag\"></\u003Cspan class=\"hljs-name\">details\u003C/span>>\u003C/span>\n\u003C/code>\u003C/pre>\u003Ch2 id=\"tools-and-generators\">Tools and Generators\u003C/h2>\n\u003Ch3 id=\"online-toc-generators\">Online TOC Generators\u003C/h3>\n\u003Cp>Several online tools can generate TOCs from existing Markdown:\u003C/p>\n\u003Col>\n\u003Cli>\u003Cstrong>\u003Ca href=\"/tools/markdown-toc\">Markdown Table of Contents Generator\u003C/a>\u003C/strong>: Paste your Markdown and get a formatted TOC automatically — generates GitHub-style anchor slugs, lets you filter by heading level, and can insert the TOC directly into your document. If you'd rather not build the anchor links by hand using the methods above, this does it for you.\u003C/li>\n\u003Cli>\u003Cstrong>GitHub TOC Generator\u003C/strong>: Specifically formats TOCs for GitHub README files\u003C/li>\n\u003Cli>\u003Cstrong>DocToc\u003C/strong>: Command-line tool for automatic TOC generation\u003C/li>\n\u003Cli>\u003Cstrong>\u003Ca href=\"/tools/markdown-editor\">Markdown Editor\u003C/a>\u003C/strong>: Live side-by-side preview — useful for writing and verifying your TOC links as you build them, without installing anything\u003C/li>\n\u003C/ol>\n\u003Ch3 id=\"editor-extensions\">Editor Extensions\u003C/h3>\n\u003Cp>Many editors offer TOC generation:\u003C/p>\n\u003Cul>\n\u003Cli>\u003Cstrong>VS Code\u003C/strong>: Markdown All in One extension\u003C/li>\n\u003Cli>\u003Cstrong>Atom\u003C/strong>: Various markdown TOC packages\u003C/li>\n\u003Cli>\u003Cstrong>Vim\u003C/strong>: vim-markdown-toc plugin\u003C/li>\n\u003C/ul>\n\u003Ch3 id=\"checking-and-maintaining-your-toc\">Checking and Maintaining Your TOC\u003C/h3>\n\u003Cp>Once you have a TOC, keeping it accurate as the document grows is the real challenge. Two tools help:\u003C/p>\n\u003Cul>\n\u003Cli>\u003Cstrong>\u003Ca href=\"/tools/markdown-diff\">Markdown Diff\u003C/a>\u003C/strong>: Compare two versions of a document to see which headings changed — useful for spotting TOC entries that need updating after a revision\u003C/li>\n\u003Cli>\u003Cstrong>\u003Ca href=\"/tools/markdown-linter\">Markdown Linter\u003C/a>\u003C/strong>: Checks heading hierarchy (e.g., skipping from H1 to H3) and flags duplicate headings that would break anchor links in your TOC\u003C/li>\n\u003C/ul>\n\u003Ch2 id=\"conclusion\">Conclusion\u003C/h2>\n\u003Cp>Creating an effective table of contents in Markdown enhances document navigation and user experience. Whether you choose automatic generation through static site generators, manual creation for maximum control, or JavaScript-based solutions for dynamic content, the key is consistency and maintaining synchronization with your document structure.\u003C/p>\n\u003Cp>The method you choose depends on your platform, technical requirements, and desired level of customization. For most use cases, a combination of manual TOC creation with automated tools provides the best balance of control and convenience.\u003C/p>\n\u003Cp>Remember to test your TOC across different platforms and devices to ensure all links function correctly and the navigation provides genuine value to your readers.\u003C/p>\n",[15,19,22,25,28,31,34,37,40,43,46],{"id":16,"text":17,"level":18},"why-add-a-table-of-contents","Why Add a Table of Contents?",2,{"id":20,"text":21,"level":18},"method-1-automatic-toc-generation","Method 1: Automatic TOC Generation",{"id":23,"text":24,"level":18},"method-2-manual-table-of-contents","Method 2: Manual Table of Contents",{"id":26,"text":27,"level":18},"method-3-javascript-based-toc-generation","Method 3: JavaScript-Based TOC Generation",{"id":29,"text":30,"level":18},"method-4-platform-specific-solutions","Method 4: Platform-Specific Solutions",{"id":32,"text":33,"level":18},"customizing-toc-appearance","Customizing TOC Appearance",{"id":35,"text":36,"level":18},"best-practices-for-toc-creation","Best Practices for TOC Creation",{"id":38,"text":39,"level":18},"troubleshooting-common-issues","Troubleshooting Common Issues",{"id":41,"text":42,"level":18},"advanced-toc-techniques","Advanced TOC Techniques",{"id":44,"text":45,"level":18},"tools-and-generators","Tools and Generators",{"id":47,"text":48,"level":18},"conclusion","Conclusion",[50,51,52,53],"markdown-toc","markdown-editor","markdown-diff","markdown-linter",[55,62,70],{"slug":56,"title":57,"description":58,"excerpt":58,"date":59,"category":9,"author":60,"keywords":61,"readingMinutes":18},"add-table-of-contents-to-markdown-using-javascript","Add table of contents to markdown using JavaScript","A table of contents, or TOC, is a useful navigation tool for long documents, allowing readers to quickly jump to different sections of the text. In markdown, a lightweight markup language used for…","2023-01-10","Matthew Rathbone (with help from OpenAI)","5/31/2023",{"slug":63,"title":64,"description":65,"excerpt":66,"date":67,"category":9,"author":10,"keywords":68,"readingMinutes":69},"markdown-collapsible-sections-guide","How to Create Collapsible Sections in Markdown: Complete Guide","Learn how to create collapsible dropdown sections in Markdown using HTML details and summary tags. Improve document organization and user experience with expandable content.","Collapsible sections are an excellent way to organize long documents and improve user experience by allowing readers to expand only the content they need. While standard Markdown doesn't include…","2025-08-15","markdown collapsible sections, markdown dropdown, markdown toggle, collapsible markdown, markdown details summary, expandable markdown sections",6,{"slug":71,"title":72,"description":73,"excerpt":74,"date":75,"category":9,"author":10,"keywords":76,"readingMinutes":18},"markdown-link-to-section","How to Create Markdown Links to Sections","Learn to interlink sections with Markdown. Tutorial on creating navigable headers using Github-Flavored Markdown syntax.","Markdown gives the ease of writing in a simple, easy-to-read, and easy-to-write plain text format. This tutorial targets software engineers and other technical professionals learning about…","2024-05-06","Markdown link to section",1792184940766]