mdformat-toc

0.5.0 verified Sat May 09 auth: no python

A plugin for mdformat that automatically generates a table of contents (TOC) in Markdown documents. Version 0.5.0, requires Python >=3.9. Release cadence is low, maintained as part of the mdformat plugin ecosystem.

pip install mdformat-toc

Common errors

error ModuleNotFoundError: No module named 'mdformat_toc' ↓

cause Plugin not installed or not in the current Python environment.

fix

Run pip install mdformat-toc to install the plugin.

error mdformat.exceptions.ParsingError: ... toc ... ↓

cause The Markdown content has syntax issues that prevent TOC generation (e.g., incomplete headings).

fix

Ensure all headers are properly formatted (e.g., no empty headings, consistent indentation).

Warnings

deprecated Python 3.8 support was dropped in version 0.4.0. Use Python 3.9+. ↓

fix Upgrade to Python 3.9+

gotcha Plugin auto-registration may not work if mdformat-toc is not installed in the same environment as mdformat. Ensure both are installed together. ↓

fix Install mdformat-toc in the same environment: pip install mdformat mdformat-toc

Imports

mdformat_toc
```
import mdformat_toc
```
Plugin is auto-discovered by mdformat; explicit import is optional.

Quickstart

Formats a Markdown string and generates a table of contents using the plugin.

import mdformat
import os

# Create a sample Markdown file
md_content = """# Title

## Section 1

Content here.

## Section 2

More content.
"""

# Format with mdformat, using the toc plugin
formatted = mdformat.text(md_content, extensions={"toc"})
print(formatted)