Source Extension

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