Attributes

AttributesExtension adds constrained HTML attributes to Markdown elements. Attribute names are explicitly allowed by AttributesPolicy before source content can use them.

Install

This extension is bundled with alto/markdown:

composer require alto/markdown

Configure

Allow the attributes required by the application:

<?php

use Alto\Markdown\Extension\Attributes\AttributesExtension;
use Alto\Markdown\Extension\Attributes\AttributesPolicy;
use Alto\Markdown\Markdown;

$markdown = Markdown::github()->with(
    new AttributesExtension(new AttributesPolicy([
        'id',
        'class',
        'title',
    ])),
);

Markdown

{#intro .lead title="Welcome home"}
# Hello

HTML

<h1 class="lead" id="intro" title="Welcome home">Hello</h1>

Options

Without an explicit policy, only id and class are allowed.

Event handler names such as onclick cannot be allowed. Attribute names are matched case-insensitively.

Security

The policy is an allowlist for attributes authored in Markdown. Event handler names are always rejected, and configured length limits bound each parsed attribute list.

URL attributes remain subject to the active HTML policy. Allow only attributes the application intends to expose to content authors.

Behavior

A block attribute list before a block decorates the next sibling. Prefix a list with : to decorate the previous sibling instead:

> Quoted text
> {: .quoted}

<blockquote>
<p class="quoted">Quoted text</p>
</blockquote>

An inline list decorates only the rendered element immediately before it:

Read the *important*{.accent} note.

<p>Read the <em class="accent">important</em> note.</p>

Attributes native to the Markdown element take precedence. Classes from the element and the attribute list are merged without duplicates.