Default Attributes

The DefaultAttributesExtension allows you to apply default HTML classes and other attributes using configuration options.

It works by applying the attributes to the nodes during the DocumentParsedEvent event - right after the nodes are parsed but before they are rendered. (As a result, it’s possible that renderers may add other attributes - the goal of this extension is only to provide custom defaults.)

Installation

This extension is bundled with league/commonmark. This library can be installed via Composer:

composer require league/commonmark

See the installation section for more details.

Usage

Configure your Environment as usual and simply add the DefaultAttributesExtension:

use League\CommonMark\Environment\Environment;
use League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension;
use League\CommonMark\Extension\CommonMark\Node\Block\Heading;
use League\CommonMark\Extension\CommonMark\Node\Inline\Link;
use League\CommonMark\Extension\DefaultAttributes\DefaultAttributesExtension;
use League\CommonMark\Extension\Table\Table;
use League\CommonMark\MarkdownConverter;
use League\CommonMark\Node\Block\Paragraph;

// Define your configuration, if needed
// Extension defaults are shown below
// If you're happy with the defaults, feel free to remove them from this array
$config = [
    'default_attributes' => [
        Heading::class => [
            'class' => static function (Heading $node) {
                if ($node->getLevel() === 1) {
                    return 'title-main';
                } else {
                    return null;
                }
            },
        ],
        Table::class => [
            'class' => 'table',
        ],
        Paragraph::class => [
            'class' => ['text-center', 'font-comic-sans'],
        ],
        Link::class => [
            'class' => 'btn btn-link',
            'target' => '_blank',
        ],
    ],
];

// Configure the Environment with all the CommonMark parsers/renderers
$environment = new Environment($config);
$environment->addExtension(new CommonMarkCoreExtension());

// Add the extension
$environment->addExtension(new DefaultAttributesExtension());

// Instantiate the converter engine and start converting some Markdown!
$converter = new MarkdownConverter($environment);
echo $converter->convertToHtml('# Hello World!');

Configuration

This extension can be configured by providing a default_attributes array. Each key in the array should be a FQCN for the node class you wish to apply the default attribute to, and the values should be a map of attribute names to attribute values.

Attribute values may be any of the following types:

Examples

Here’s an example that will apply Bootstrap 4 classes and attributes:

$config = [
    'default_attributes' => [
        Table::class => [
            'class' => ['table', 'table-responsive'],
        ],
        BlockQuote::class => [
            'class' => 'blockquote',
        ],
    ],
];

Here’s a more complex example that uses a callable to add a class only if the paragraph immediately follows an <h1> heading:

$config = [
    'default_attributes' => [
        Paragraph::class => [
            'class' => static function (Paragraph $paragraph) {
                if ($paragraph->previous() instanceof Heading && $paragraph->previous()->getLevel() === 1) {
                    return 'lead';
                }

                return null;
            },
        ],
    ],
];

Edit this page