matfire/commonmark-directives

A CommonMark extension for text, leaf, and container directives.

v0.0.1 2026-08-13 18:02 UTC

Requires

• php: ^8.4
• league/commonmark: ^2.10
• psr/container: ^2.0

Requires (Dev)

• laravel/pint: ^1.29
• pestphp/pest: ^5.0
• pestphp/pest-plugin-type-coverage: ^5.0

MIT

• markdown
• commonmark
• directives

Published on Packagist.org on 2026-08-13 18:04 UTC

README

CommonMark Directives

CommonMark Directives

A league/commonmark extension for rendering registered text, leaf, and container directives through small PHP components.

Installation

composer require matfire/commonmark-directives

Usage

Create a component that returns the directive's HTML:

use Matfire\CommonMarkDirectives\MarkdownComponent;
use Matfire\CommonMarkDirectives\MarkdownComponentParameters;

final class Badge implements MarkdownComponent
{
    public function render(MarkdownComponentParameters $parameters): string
    {
        return sprintf('<span>%s</span>', htmlspecialchars($parameters->label ?? ''));
    }
}

Register it with a CommonMark environment and a PSR-11 container:

use League\CommonMark\Environment\Environment;
use League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension;
use League\CommonMark\MarkdownConverter;
use Matfire\CommonMarkDirectives\MarkdownComponentDefinition;
use Matfire\CommonMarkDirectives\MarkdownComponentsExtension;

$environment = new Environment;
$environment->addExtension(new CommonMarkCoreExtension);
$environment->addExtension(new MarkdownComponentsExtension([
    MarkdownComponentDefinition::text('badge', Badge::class),
], $container));

$converter = new MarkdownConverter($environment);
$html = $converter->convert('Built with :badge[Laravel]{tone=red}.');

The container must implement Psr\Container\ContainerInterface and resolve each registered component class.

Syntax

:badge[Laravel]{tone=red}

::youtube[Video title]{id=jjKFXlFNR4E}

:::callout{type=warning}
Container content supports **Markdown**.
:::

• text() registers inline directives beginning with :.
• leaf() registers standalone block directives beginning with ::.
• container() registers fenced block directives beginning with :::.
• Attributes support quoted or unquoted values, boolean attributes, #id, and .class shortcuts.
• Only registered name-and-type combinations are parsed as directives.

Testing

composer test

License

MIT