Twig

The flexible, fast, and secure
template engine for PHP

a Symfony Product
Docs Filters markdown_to_html
Docs for Twig version 3.x
Switch to another version: 1.x, 2.x

Questions & Feedback

License

Twig documentation is licensed under the new BSD license.

markdown_to_html

The markdown_to_html filter converts a block of Markdown to HTML:

1
2
3
4
5
6
{% apply markdown_to_html %}
Title
=====

Hello!
{% endapply %}

Note that you can indent the Markdown content as leading whitespaces will be removed consistently before conversion:

1
2
3
4
5
6
{% apply markdown_to_html %}
    Title
    =====

    Hello!
{% endapply %}

You can also use the filter on an included file or a variable:

1
2
3
{{ include('some_template.markdown.twig')|markdown_to_html }}

{{ changelog|markdown_to_html }}

Note

The markdown_to_html filter is part of the MarkdownExtension which is not installed by default. Install it first:

1
$ composer require twig/markdown-extra

Then, on Symfony projects, install the twig/extra-bundle:

1
$ composer require twig/extra-bundle

Otherwise, add the extension explicitly on the Twig environment:

1
2
3
4
use Twig\Extra\Markdown\MarkdownExtension;

$twig = new \Twig\Environment(...);
$twig->addExtension(new MarkdownExtension());

If you are not using Symfony, you must also register the extension runtime:

1
2
3
4
5
6
7
8
9
10
11
use Twig\Extra\Markdown\DefaultMarkdown;
use Twig\Extra\Markdown\MarkdownRuntime;
use Twig\RuntimeLoader\RuntimeLoaderInterface;

$twig->addRuntimeLoader(new class implements RuntimeLoaderInterface {
    public function load($class) {
        if (MarkdownRuntime::class === $class) {
            return new MarkdownRuntime(new DefaultMarkdown());
        }
    }
});

Afterwards you need to install a markdown library of your choice. Some of them are mentioned in the require-dev section of the twig/markdown-extra package.

Note

If using Symfony (full-stack), twig/extra-bundle with league/commonmark as your Markdown library you can configure CommonMark extensions. Register the desired extension(s) as a service, then tag the service with twig.markdown.league_extension.

Using a Custom Converter

The markdown_to_html filter delegates the conversion to a class implementing Twig\Extra\Markdown\MarkdownInterface. Several implementations are provided: LeagueMarkdown (league/commonmark), MichelfMarkdown (michelf/php-markdown), ErusevMarkdown (erusev/parsedown), and TempestMarkdown (tempest/markdown). Each accepts a pre-configured converter in its constructor, so you can tune the underlying library or switch to another implementation (for instance ParsedownExtra, which extends Parsedown):

1
2
3
4
5
6
use Twig\Extra\Markdown\ErusevMarkdown;

$parsedown = new \ParsedownExtra();
$parsedown->setSafeMode(true);

$markdown = new ErusevMarkdown($parsedown);

Note

tempest/markdown requires PHP 8.5 or later. It also differs from the other libraries on two points worth knowing about: Setext headings (Title underlined with ===) are not supported, so use ATX headings (# Title) instead, and any YAML front matter is parsed out of the rendered HTML rather than being rendered.

Caution

The output of the filter is marked as safe for HTML. The default tempest/markdown converter passes raw HTML, raw @@ ... @@ blocks, and unsafe links through, so only use it on trusted input, or pass a converter configured to sanitize its output to TempestMarkdown.

When using twig/extra-bundle, register your converter as the twig.markdown.default service to make it the one used by the filter:

1
2
3
4
5
6
# config/services.yaml
services:
    twig.markdown.default:
        class: Twig\Extra\Markdown\ErusevMarkdown
        arguments:
            - '@my_configured_parsedown'

If you use league/commonmark, prefer the commonmark configuration of the bundle (for example html_input: escape and allow_unsafe_links: false to protect against XSS) instead of replacing the service.

« map | merge »