alto/commonmark-import

CommonMark extension that embeds raw file content at @import directives, with line range, language, and indent options.

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

Requires

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

MIT

• Simon André

• php
• import
• markdown
• snippet
• commonmark
• alto
• commonmark-extension
• file-embed
• code-embed

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

README

Summary

Solves the copy-paste drift problem between documentation and source code. @import directives pull external file content directly into fenced code blocks at parse time -- with optional line-range selection, language hinting, and indentation control. Your code samples stay in sync with the actual source by definition, not by discipline.

Installation

composer require

composer require alto/commonmark

Registration

use Alto\CommonMark\Extension\Import\ImportExtension;
use League\CommonMark\Environment\Environment;

$environment = new Environment();
$environment->addExtension(new ImportExtension(__DIR__ . '/docs'));

Usage

@import "path/to/file.md"
@import "src/Handler.php" {lines: 10-40, lang: php, indent: 2}

Configuration

• Constructor: new ImportExtension(string $basePath = '.', int $maxDepth = 10).
• Guards against circular imports and excessive nesting depth.

Minimal Example

# API

@import "snippets/auth.md"
@import "src/Auth.php" {lines: 1-30, lang: php}

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