Skip to content
Twig extension to work with Markdown content
Branch: master
Clone or download
Latest commit 9046974 Dec 11, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
src/Aptoma/Twig Update ParsedownEngine to set HTML escaping May 16, 2019
tests/Aptoma/Twig Add tests for new functions May 22, 2019
.travis.yml Support Twig 3. Dec 10, 2019 Release 3.2.0 May 24, 2019 [doc] Usage in Symfony app Sep 12, 2019
composer.json Support Twig 3. Dec 10, 2019

Twig Markdown Extension

Build Status

Twig Markdown extension provides a new filter and a tag to allow parsing of content as Markdown in Twig templates.

This extension could be integrated with several Markdown parser as it provides an interface, which allows you to customize your Markdown parser.

Supported parsers


  • Filter support {{ "# Heading Level 1"|markdown }}
  • Tag support {% markdown %}{% endmarkdown %}

When used as a tag, the indentation level of the first line sets the default indentation level for the rest of the tag content. From this indentation level, all same indentation or outdented levels text will be transformed as regular text.

This feature allows you to write your Markdown content at any indentation level without caring of Markdown internal transformation:

    <h1 class="someClass">{{ title }}</h1>

    {% markdown %}
    This is a list that is indented to match the context around the markdown tag:

    * List item 1
    * List item 2
        * Sub List Item
            * Sub Sub List Item

    The following block will be transformed as code, as it is indented more than the
    surrounding content:

        $code = "good";

    {% endmarkdown %}



Run the composer command to install the latest stable version:

composer require aptoma/twig-markdown

Or update your composer.json:

    "require": {
        "aptoma/twig-markdown": "~3.0"

You can choose to provide your own Markdown engine, although we recommend using michelf/php-markdown:

composer require michelf/php-markdown ~1.8
    "require": {
        "michelf/php-markdown": "~1.8"

You may also use the PHP League CommonMark engine:

composer require league/commonmark ~0.19
    "require": {
        "league/commonmark": "~0.19"


Twig Extension

The Twig extension provides the markdown tag and filter support.

Assuming that you are using composer autoloading, add the extension to the Twig environment:

use Aptoma\Twig\Extension\MarkdownExtension;
use Aptoma\Twig\Extension\MarkdownEngine;

$engine = new MarkdownEngine\MichelfMarkdownEngine();

$twig->addExtension(new MarkdownExtension($engine));

Twig Token Parser

The Twig token parser provides the markdown tag only!

use Aptoma\Twig\Extension\MarkdownEngine;
use Aptoma\Twig\TokenParser\MarkdownTokenParser;

$engine = new MarkdownEngine\MichelfMarkdownEngine();

$twig->addTokenParser(new MarkdownTokenParser($engine));


To use this extension in a Symfony 3/4 app (including Pimcore), add the following snippet to your app's app/config/services.yml file:

    # ...
        class: Aptoma\Twig\Extension\MarkdownEngine\MichelfMarkdownEngine
        class: Aptoma\Twig\Extension\MarkdownExtension
        arguments: ['@markdown.engine']
            - { name: twig.extension }

GitHub Markdown Engine

MarkdownEngine\GitHubMarkdownEngine provides an interface to GitHub's markdown engine using their public API via KnpLabs\php-github-api. To reduce API calls, rendered documents are hashed and cached in the filesystem. You can pass a GitHub repository and the path to be used for caching to the constructor:

use Aptoma\Twig\Extension\MarkdownEngine;

$engine = new MarkdownEngine\GitHubMarkdownEngine(
    'aptoma/twig-markdown', // The GitHub repository to use as a context
    true,                   // Whether to use GitHub's Flavored Markdown (GFM)
    '/tmp/markdown-cache',  // Path on filesystem to store rendered documents

In order to authenticate the API client (for instance), it's possible to pass an own instance of \GitHub\Client instead of letting the engine create one itself:

$client = new \Github\Client;
$client->authenticate('GITHUB_CLIENT_ID', 'GITHUB_CLIENT_SECRET', \Github\Client::AUTH_URL_CLIENT_ID);

$engine = new MarkdownEngine\GitHubMarkdownEngine('aptoma/twig-markdown', true, '/tmp/markdown-cache', $client);

Using a different Markdown parser engine

If you want to use a different Markdown parser, you need to create an adapter that implements Aptoma\Twig\Extension\MarkdownEngineInterface.php. Have a look at Aptoma\Twig\Extension\MarkdownEngine\MichelfMarkdownEngine for an example.


The test suite uses PHPUnit:

$ phpunit


Twig Markdown Extension is licensed under the MIT license.

You can’t perform that action at this time.