alto/commonmark-source

CommonMark extension that displays source files as highlighted code blocks at @source directives, with title, line numbers, and highlighting.

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

Requires

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

MIT

• Simon André

• php
• source
• markdown
• syntax-highlight
• source-code
• commonmark
• alto
• commonmark-extension
• code-block

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

README

Summary

The flagship of the set. @source directives embed a real file -- not a copy -- into your documentation at parse time, with automatic syntax class detection, precise line-range selection, optional line numbers, and per-line highlighting. Your docs and your source stay in sync by construction.

Installation

composer require

composer require alto/commonmark

Registration

use Alto\CommonMark\Extension\Source\SourceExtension;
use League\CommonMark\Environment\Environment;

$environment = new Environment();
$environment->addExtension(new SourceExtension(__DIR__));

Usage

@source "src/Service.php"
@source "src/Service.php" {lines: 10-30, numbers: true, highlight: "14,18-20"}

Configuration

• Constructor: new SourceExtension(string $basePath='.', array $allowedExtensions=[], bool $escapeHtml=true, int $maxFileSize=1048576).
• Supports extension allowlists and max-size protections.

Minimal Example

# Service excerpt

@source "src/Service.php" {lines: 1-25, numbers: true}

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