README

Render your markdown by your favorite template library

CommonMark Template Renderer Extension is an extension for League CommonmMark to render the html elements via your favorite template engine.

Warning

At the moment, we support only Twig. We scheduled Latte, Blade and Plates support to version 1.0

Why render html elements via templates?

The answer is simple: easy html customization. And it's the only reason to use this library. In fact, the defaul templates generate exactly the same output as standard renderers. But template engines introduce some complexity and a little overhead so if you don't customize your html you don't need to use this library.

Installation

Install the extension via Composer:

composer require pomodocs/commonmark-template-renderer

Basic Usage

After installing it, register the extension in your Commonmark Environment:

<?php

require __DIR__ . '/vendor/autoload.php';

use League\CommonMark\Environment\Environment;
use League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension;
use PomoDocs\CommonMark\TemplateRenderer\TemplateConverter;
use PomoDocs\CommonMark\TemplateRenderer\TemplateRendererExtension;

$config = [
    'templateRenderer' => [
        'engine' => 'twig',
        'templates_dirs' => [
            '/my/templates/dir',
            '/another/templates/dir',
        ],
    ]
];

$environment = new Environment($config);
$environment->addExtension(new CommonMarkCoreExtension());
$environment->addExtension(.....); // add your favorite extensions
$environment->addExtension(new TemplateRendrerExtension());

$converter = new TemplateConverter($environment);

Now you're ready to convert your html.

Configuration

You can configure the library by passing an array with templateRenderer key to the Environment object:

<?php

use League\CommonMark\Environment\Environment;


$config = [
    'templateRenderer' => [
        'engine' => 'twig',
        'templates_dirs' => [
            '/my/templates/dir',
            '/another/templates/dir',
        ],
    ]
];

$environment = new Environment($config);

Let's explain the configuration keys:

• engine: the template engine by which we render our templates. Supported engines are: twig, latte, blade, plates. Default to twig.
• templates_dirs: an array of directories where the engine looks for the templates. The dafult directory, containing the templates shipped by the library, is automatically included.

Customize your html

Let's introduce the goal of this library: easy customization of your html fragments. We try to explain it via a simple example.

Let's suppose we wanto to use Bulma css framework and we want to style headings nodes by Bulma title class. When we write the following markdown:

# Title 1
## Title 2
### Title 3

our resulting html should be:

<h1 class="title is-1">Title 1</h1>
<h2 class="title is-2">Title 2</h2>
<h3 class="title is-3">Title 3</h3>

Every node is rendered by a small template. You can see the full templates list in https://github.com/pomodocs/commonmark-template-renderer/tree/master/resources/templates/default/twig.

Heading node is rendered via heading.html.twig template so we create a directory where our custom template resides (i.e. resources/templates) and create the heading.html.twig file. For the first shot, you can copy-paste https://github.com/pomodocs/commonmark-template-renderer/blob/master/resources/templates/default/twig/heading.html.twig.

The content of the copied file is the following:

<h{{ node.level }}{{ node|render_attributes }}>{{ node|render_children }}</h{{ node.level }}>

Our engine passes two variables to the templates: node and configuration.

• node variable contains a Node object, in our example a Heading node instance.
• configurationvariable contains a complete configuration object.

The content of our custom template resources\templates\heading.html.twig could be the following:

<h{{ node.level }} class="title is-{{ node.level }}>{{ node|render_children }}</h{{ node.level }}>

Important

This library ships two filters we can apply to node objects:

• render_children filter renders all the children of the given node.
• render_attributes filter renders all the attributes (class, name, type etc.) of the given node.

Now, you can convert your markdown into html:

<?php

use League\CommonMark\Environment\Environment;
use League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension;
use PomoDocs\CommonMark\TemplateRenderer\TemplateConverter;
use PomoDocs\CommonMark\TemplateRenderer\TemplateRendererExtension;

$config = [
    'templateRenderer' => [
        'engine' => 'twig',
        'templates_dirs' => [
            __DIR__ . '/resources/templates',
        ],
    ]
];

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

$converter = new TemplateConverter($environment);

$converter->convert("
# Title 1
## Title 2
### Title 3"
);

// The result is:
// <h1 class="title is-1">Title 1</h1>
// <h2 class="title is-2">Title 2</h2>
// <h3 class="title is-3">Title 3</h3>

Issues

Please, open an issue on Github repository.

Contributing

Please, see our Contributing guide.

Licensing

This library is released under MIT license.