mdformat-ado-toc

[[TOC]]

An mdformat plugin that preserves Azure DevOps' [[_TOC_]] directive. mdformat normally escapes it to \[\[_TOC_\]\]. This plugin treats it as a custom block and renders it back verbatim.

Problem

Azure DevOps wikis use [[_TOC_]] to generate a table of contents. However, when formatting markdown files with mdformat, the brackets get escaped to \[\[_TOC_\]\], which breaks the TOC functionality.

Solution

This plugin registers a custom parser extension that recognizes [[_TOC_]] as a special block element and preserves it without escaping during formatting.

Features

• ✅ Preserves [[_TOC_]] without escaping brackets
• ✅ Handles surrounding whitespace correctly
• ✅ Supports multiple TOC markers in one document
• ✅ Works correctly when mixed with other markdown content
• ✅ Uses Python type hints and modern Python syntax

How It Works

The plugin implements a custom markdown-it parser rule that:

1. Intercepts lines containing [[_TOC_]] before they are parsed as paragraphs
2. Creates a custom ado_toc token for these lines
3. Renders the token back as the literal string [[_TOC_]] without escaping

Install

pip install mdformat-ado-toc
# or from source
pip install -e .

Usage

Command Line

mdformat document.md --extensions ado_toc

Usage as pre-commit hook

You can run mdformat (with this plugin) automatically before commits using pre-commit.
Just add the following to your .pre-commit-config.yaml:

- repo: https://github.com/executablebooks/mdformat
  rev: 1.0.0
  hooks:
    - id: mdformat
      additional_dependencies:
        - mdformat-ado-toc  # This plugin

Python API

import mdformat

text = """
# My Document

[[_TOC_]]

## Section 1
Content here.
"""

formatted = mdformat.text(text, extensions=["ado_toc"])
print(formatted)  # [[_TOC_]] is preserved!

Testing

pytest tests/test_plugin.py -v

License

MIT