Versions

Getting Started

Usage

Extensions

Customization

This is the documentation for the unsupported version 2.2. Please consider upgrading your code to the latest stable version

Custom Rendering

Renderers are responsible for converting the parsed AST elements into their HTML representation.

All block renderers should implement NodeRendererInterface and its render() method. Note that in v2.0, both block renderers and inline renderers share the same interface and method:

render()

public function render(Node $node, ChildNodeRendererInterface $childRenderer);

The HtmlRenderer will call this method during the rendering process whenever a supported element is encountered.

If your renderer can only handle certain block types, be sure to verify that you’ve been passed the correct type.

Parameters

Return value

The method must return the final HTML representation of the node and its contents, including any children. This can be an HtmlElement object (preferred; castable to a string), a string of raw HTML, or null if it could not render (and perhaps another renderer should give it a try).

If you choose to return an HTML string you are responsible for handling any escaping that may be necessary.

HtmlElement

Instead of manually building the HTML output yourself, you can leverage the HtmlElement to generate that for you. For example:

use League\CommonMark\Util\HtmlElement;

$link = new HtmlElement('a', ['href' => 'https://github.com'], 'GitHub');
$img = new HtmlElement('img', ['src' => 'logo.jpg'], '', true);

Designating Renderers

When registering your renderer, you must tell the Environment which node element class your renderer should handle. For example:

use League\CommonMark\Environment\Environment;
use League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension;
use League\CommonMark\Extension\CommonMark\Node\Block\FencedCode;

$environment = new Environment();
$environment->addExtension(new CommonMarkCoreExtension());

// First param - the node class type that should use our renderer
// Second param - instance of the renderer
$environment->addRenderer(FencedCode::class, new MyCustomCodeRenderer());

A single renderer could even be used for multiple types:

use League\CommonMark\Environment\Environment;
use League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension;
use League\CommonMark\Extension\CommonMark\Node\Block\FencedCode;
use League\CommonMark\Extension\CommonMark\Node\Block\IndentedCode;

$environment = new Environment();
$environment->addExtension(new CommonMarkCoreExtension());

$myRenderer = new MyCustomCodeRenderer();

$environment->addRenderer(FencedCode::class, $myRenderer, 10);
$environment->addRenderer(IndentedCode::class, $myRenderer, 20);

Multiple renderers can be added per element type - when this happens, we use the result from the highest-priority renderer that returns a non-null result.

Example

Here’s a custom renderer which renders thematic breaks as text (instead of <hr>):

use League\CommonMark\Environment\Environment;
use League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension;
use League\CommonMark\Extension\CommonMark\Node\Block\ThematicBreak;
use League\CommonMark\Node\Node;
use League\CommonMark\Renderer\ChildNodeRendererInterface;
use League\CommonMark\Renderer\NodeRendererInterface;
use League\CommonMark\Util\HtmlElement;

class TextDividerRenderer implements NodeRendererInterface
{
    public function render(Node $node, ChildNodeRendererInterface $childRenderer)
    {
        return new HtmlElement('pre', ['class' => 'divider'], '==============================');
    }
}

$environment = new Environment();
$environment->addExtension(new CommonMarkCoreExtension());
$environment->addRenderer(ThematicBreak::class, new TextDividerRenderer());

Note that thematic breaks should not contain children, which is why the $childRenderer is unused in this example. Otherwise we’d have to call code like this and return the result as part of the rendered HTML we’re generating here: $innerHtml = $childRenderer->renderNodes($node->children());

Tips

Wrapping Elements with HtmlDecorator

A utility class called HtmlDecorator is provided to make it easier to wrap the output of any renderer within an additional HTML tag with custom attributes and/or classes.

To use it, you register it as a renderer for whatever AST node type you want to wrap:

use League\CommonMark\Environment\Environment;
use League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension;
use League\CommonMark\Extension\Table\Table;
use League\CommonMark\Extension\Table\TableExtension;
use League\CommonMark\Extension\Table\TableRenderer;
use League\CommonMark\Renderer\HtmlDecorator;

$environment = new Environment();
$environment->addExtension(new CommonMarkCoreExtension());
$environment->addExtension(new TableExtension());
$environment->addRenderer(Table::class, new HtmlDecorator(new TableRenderer(), 'div', ['class' => 'table-responsive']));

XML Rendering

The XML renderer will automatically attempt to convert any AST nodes to XML by inspecting the name of the block/inline node and its attributes. You can instead control the XML element name and attributes by making your renderer implement XmlNodeRendererInterface:

use League\CommonMark\Node\Node;
use League\CommonMark\Renderer\ChildNodeRendererInterface;
use League\CommonMark\Renderer\NodeRendererInterface;
use League\CommonMark\Util\HtmlElement;
use League\CommonMark\Xml\XmlNodeRendererInterface;

class TextDividerRenderer implements NodeRendererInterface, XmlNodeRendererInterface
{
    public function render(Node $node, ChildNodeRendererInterface $childRenderer)
    {
        return new HtmlElement('pre', ['class' => 'divider'], '==============================');
    }

    public function getXmlTagName(Node $node): string
    {
        return 'text_divider';
    }

    public function getXmlAttributes(Node $node): array
    {
        return ['character' => '='];
    }
}

Edit this page