alto/commonmark-content-slicer

CommonMark extension that wraps heading-based sections in nested <section> elements for semantic document structure.

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

Requires

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

MIT

• Simon André

• php
• markdown
• section
• commonmark
• heading
• alto
• semantic-html
• commonmark-extension
• sectioning

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

README

Summary

Genuinely rare in the CommonMark ecosystem. Most processors stop at rendering headings as <h1>…<h6> tags -- this one goes further and restructures the document into a properly nested <section> tree that mirrors the heading hierarchy. The result is semantic HTML you can actually target with CSS, query with JavaScript, and traverse with accessibility tooling. No custom syntax required.

Installation

composer require

composer require alto/commonmark

Registration

use Alto\CommonMark\Extension\ContentSlicer\ContentSlicerExtension;
use League\CommonMark\Environment\Environment;

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

Usage

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

Configuration

• Constructor: new ContentSlicerExtension(int $minSectionLevel = 1).
• 0 wraps from h1, 1 wraps from h2, 2 wraps from h3, etc.

Minimal Example

# Title
Intro

## Section

Body
### Subsection

Details

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