Download the PHP package develate/commonmark-customtags without Composer

commonmark-customtags

A league/commonmark v2 extension for inline custom tags such as:

The extension parses the content between the delimiters, uses the first token as a tag identifier, supports quoted argument values, URL-decodes the remaining arguments, and delegates rendering to your own Customtag classes.

Installation

Requirements:

• PHP 8.0 or newer
• league/commonmark 2.x

Basic Usage

Register the extension on a CommonMark environment and add one or more tags:

Output:

Tag Syntax

The default delimiters are {{ and }}.

Inside the delimiters:

• The first token is the tag identifier.
• Remaining tokens become arguments.
• Tokens are separated by spaces unless wrapped in double quotes.
• key=value tokens become named arguments.
• Tokens without = become positional arguments.
• Argument values can be wrapped in double quotes when they contain spaces.
• Argument values are still decoded with urldecode(), so existing %20 or + inputs keep working.
• Use %22 inside quoted values when you need a literal double quote.

For example:

is passed to the matching tag as:

If a tag identifier is not registered, the inner text is rendered unchanged and the delimiters are removed.

Custom tags are intended for plain command-style text. Put the tag name first, provide at least one token, and wrap argument values that contain spaces in double quotes. URL-encoded values are still supported for compatibility.

Creating Tags

Create a class that extends Develate\CommonmarkCustomtags\Customtag.

Register it with the extension:

Then use it in Markdown:

Normalizing Arguments

Override makeArguments() when a tag should validate or normalize its arguments before rendering:

Markdown:

Shared Globals

Pass shared context into the extension constructor. The same value is provided to every tag's render() method as $globals.

Use it inside a tag:

$globals can be an array, object, service container, or any other value your tags know how to consume.

Custom Delimiters

You can change the opening and closing delimiters:

Markdown:

Delimiter rules:

• Opening and closing delimiters must have the same length.
• Each delimiter must be made by repeating one character.
• Valid examples: {{ and }}, [[ and ]], (( and )), %% and %%.
• Invalid examples: <% and %>, {% and %}.

These rules come from the way league/commonmark delimiter processors match character runs.

Registering Tags in the Constructor

Tags can also be passed directly to the constructor. The array keys must be the tag identifiers:

Using addTag() is usually simpler because it keys the tag by identifier() for you.

Escaping and Security

Rendered tag output is returned directly to CommonMark. Escape any user-controlled values yourself before returning HTML.

Recommended helpers:

If a tag should not render anything, return null or an empty string from render().

Full Example