alto/commonmark-table-of-contents

CommonMark extension that generates a linked table of contents from document headings at @toc directives.

v1.0.0 2026-07-30 02:00 UTC

Requires

• php: ^8.3
• league/commonmark: ^2.7

MIT

• Simon André

• php
• markdown
• TOC
• commonmark
• summary
• heading
• alto
• table-of-contents
• commonmark-extension
• markdown-toc

Published on Packagist.org on 2026-07-30 02:56 UTC

README

Summary

A must-have for any document longer than a page. Place @toc where you want the contents list and the extension takes care of the rest: headings are collected, anchor IDs are assigned, and a navigable nested list is rendered -- with filtering by level and configurable output style.

Installation

composer require

composer require alto/commonmark

Registration

use Alto\CommonMark\Extension\TableOfContents\TableOfContentsExtension;
use League\CommonMark\Environment\Environment;

$environment = new Environment();
$environment->addExtension(new TableOfContentsExtension());

Usage

@toc
@toc {min: 2, max: 3, title: "Contents", style: ordered}

Configuration

• min_level / max_level: heading level bounds.
• style: bullet or ordered.
• title, class, id, marker: output/customization options.

Minimal Example

# Guide
@toc {min: 2}

## Intro

## Setup

### Advanced Setup

Development

This extension is actively developed in the alto/commonmark monorepo.

• Report a bug
• Suggest a feature
• Open a Pull Request

License

MIT License -- Simon André & Alto