1``html_to_markdown``
2====================
3
4.. versionadded:: 2.12
5
6    The ``html_to_markdown`` filter was added in Twig 2.12.
7
8The ``html_to_markdown`` filter converts a block of HTML to Markdown:
9
10.. code-block:: html+twig
11
12    {% apply html_to_markdown %}
13        <html>
14            <h1>Hello!</h1>
15        </html>
16    {% endapply %}
17
18You can also use the filter on an entire template which you ``include``:
19
20.. code-block:: twig
21
22    {{ include('some_template.html.twig')|html_to_markdown }}
23
24.. note::
25
26    The ``html_to_markdown`` filter is part of the ``MarkdownExtension`` which
27    is not installed by default. Install it first:
28
29    .. code-block:: bash
30
31        $ composer require twig/markdown-extra
32
33    On Symfony projects, you can automatically enable it by installing the
34    ``twig/extra-bundle``:
35
36    .. code-block:: bash
37
38        $ composer require twig/extra-bundle
39
40    Or add the extension explicitly on the Twig environment::
41
42        use Twig\Extra\Markdown\MarkdownExtension;
43
44        $twig = new \Twig\Environment(...);
45        $twig->addExtension(new MarkdownExtension());
46
47    If you are not using Symfony, you must also register the extension runtime::
48
49        use Twig\Extra\Markdown\DefaultMarkdown;
50        use Twig\Extra\Markdown\MarkdownRuntime;
51        use Twig\RuntimeLoader\RuntimeLoaderInterface;
52
53        $twig->addRuntimeLoader(new class implements RuntimeLoaderInterface {
54            public function load($class) {
55                if (MarkdownRuntime::class === $class) {
56                    return new MarkdownRuntime(new DefaultMarkdown());
57                }
58            }
59        });
60
61``html_to_markdown`` is just a frontend; the actual conversion is done by one of
62the following compatible libraries, from which you can choose:
63
64* `erusev/parsedown`_
65* `league/html-to-markdown`_
66* `michelf/php-markdown`_
67
68Depending on the library, you can also add some options by passing them as an argument
69to the filter. Example for ``league/html-to-markdown``:
70
71.. code-block:: html+twig
72
73    {% apply html_to_markdown({hard_break: false}) %}
74        <html>
75            <h1>Hello!</h1>
76        </html>
77    {% endapply %}
78
79.. _erusev/parsedown: https://github.com/erusev/parsedown
80.. _league/html-to-markdown: https://github.com/thephpleague/html-to-markdown
81.. _michelf/php-markdown: https://github.com/michelf/php-markdown
82