Import

ImportExtension reads a bounded resource and renders its bytes as an escaped code block without parsing them as Markdown.

Install

ImportExtension is bundled with alto/markdown.

composer require alto/markdown

Configure

<?php

use Alto\Markdown\Extension\Import\ImportExtension;
use Alto\Markdown\Markdown;
use Alto\Markdown\Resource\FilesystemResourceResolver;

$resolver = new FilesystemResourceResolver(
    root: __DIR__.'/content',
    allowedExtensions: ['php'],
    maxBytes: 100_000,
);

$markdown = Markdown::commonmark()->with(new ImportExtension($resolver));

Assume content/snippet.php contains:

<?php
echo 'Hello';

Markdown

@import "snippet.php" {lang: php}

HTML

<pre><code class="language-php">&lt;?php
echo &apos;Hello&apos;;
</code></pre>

Options

Options follow the quoted resource reference inside braces.

Option	Default	Effect
`lines`	All lines	Selects one 1-based line or an inclusive range such as `2-8`
`lang`	None	Adds the corresponding `language-*` class to the code element
`indent`	`0`	Adds up to 32 spaces to every imported line

Line numbers cannot exceed 1,000,000. Language identifiers are limited to 64 bytes. An invalid directive remains literal and performs no resource read.

Security

The directive must start at column zero outside an open paragraph. Imported bytes are always escaped as code, including under permissive HTML policies. Resolution happens once while parsing; later renders perform no I/O.

The resolver defines the available resources. FilesystemResourceResolver accepts relative paths only, rejects parent traversal and symlink components, and enforces both the extension allowlist and maxBytes.