Code block titles

CodeBlockTitleExtension reads a title from a fenced code block's info string. It wraps the code block in a figure with a visible caption.

Install

This extension is bundled with alto/markdown:

composer require alto/markdown

Configure

Add the extension to any factory profile:

<?php

use Alto\Markdown\Extension\CodeBlockTitle\CodeBlockTitleExtension;
use Alto\Markdown\Markdown;

$markdown = Markdown::github()->with(new CodeBlockTitleExtension());

Markdown

```php title="src/App.php"
<?php echo 1;

HTML

<figure class="code-block has-title" data-title="src/App.php">
<figcaption class="code-title">src/App.php</figcaption>
<pre><code class="language-php">&lt;?php echo 1;
</code></pre>
</figure>

Options

Pass a CodeBlockTitlePolicy to change the wrapper or parser limits:

<?php

use Alto\Markdown\Extension\CodeBlockTitle\CodeBlockTitlePolicy;

$extension = new CodeBlockTitleExtension(new CodeBlockTitlePolicy(
    figureClass: 'code-block',
    captionClass: 'code-block-title',
    includeDataTitle: false,
));

Option	Default	Purpose
`figureClass`	`code-block has-title`	Classes added to the figure
`captionClass`	`code-title`	Class added to the caption
`includeDataTitle`	`true`	Add the title as `data-title` on the figure
`maxInfoBytes`	`4096`	Maximum fenced-code info string length
`maxTitleBytes`	`512`	Maximum decoded title length

Security

The title and code content are escaped before insertion into HTML. Parser limits bound the info string and decoded title. The extension performs no I/O and does not enable raw HTML.

Behavior

Both quoted and unquoted values are accepted. filename is an alias when no title is present. If both appear, title takes precedence.

A missing, malformed, or oversized title leaves the ordinary <pre><code> output unchanged.