alto/commonmark-heading-level

CommonMark extension that shifts, maps, or transforms heading levels via a config array or callback.

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

Requires

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

MIT

• Simon André

• php
• markdown
• commonmark
• heading
• alto
• commonmark-extension
• heading-level
• heading-shift

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

README

Summary

The one you don't need until you really do -- then it's irreplaceable. Transforms heading levels after parsing so that content written for one heading context can be safely embedded in another without hierarchy collisions. Supports fixed shifting, explicit level remapping, and a callback option that gives you complete control over every heading in the document.

Installation

composer require

composer require alto/commonmark

Registration

use Alto\CommonMark\Extension\HeadingLevel\HeadingLevelExtension;
use League\CommonMark\Environment\Environment;

$environment = new Environment();
$environment->addExtension(new HeadingLevelExtension(['down' => 1]));

Usage

No custom markdown directive is required; the extension processes standard headings after parse.

Configuration

• ['down' => 1]: shifts heading level up numerically (h1 -> h2, etc.).
• ['map' => [1 => 2, 2 => 3]]: explicit per-level mapping.
• ['callback' => fn(int $level): int => ...]: custom transformation logic.

Minimal Example

# Original H1

## Original H2

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