Twig Markdown Extra

Twig Markdown Extra is an official Twig extension that adds Markdown support to your templates. It provides a markdown_to_html filter to convert Markdown blocks into HTML and an html_to_markdown filter to do the reverse, so content authored in Markdown can be rendered inline wherever Twig is used.

The extension is deliberately engine-agnostic: it defines a small MarkdownInterface and ships adapters for League CommonMark, Parsedown (Erusev), and PHP Markdown (Michelf), letting you choose whichever Markdown parser fits your project or plug in your own. It integrates cleanly with Symfony via a runtime class so the parser is only instantiated when actually needed.

What You Get

• A markdown_to_html Twig filter that safely renders Markdown blocks as HTML
• An html_to_markdown filter for converting HTML back into Markdown
• A MarkdownInterface with adapters for CommonMark, Parsedown, and PHP Markdown
• A lazy Twig runtime so the Markdown parser is only created when a template uses it
• Symfony and standalone Twig integration with is_safe HTML output handling

Common Use Cases

• Rendering user- or CMS-authored Markdown content inside Twig templates
• Displaying Markdown-formatted documentation, changelogs, or blog posts on a site
• Converting rich HTML email or editor output into Markdown for storage
• Choosing a specific Markdown flavor (CommonMark, Parsedown, or PHP Markdown) per project

Under The Hood

Architecture - MarkdownExtension registers two TwigFilters. The markdown_to_html filter delegates to MarkdownRuntime::convert, a lazily instantiated runtime that holds a MarkdownInterface implementation; html_to_markdown is a static method backed by League’s HtmlConverter. Concrete parsers are wrapped by adapter classes (LeagueMarkdown, ErusevMarkdown, MichelfMarkdown, DefaultMarkdown) that all implement MarkdownInterface, so the extension never hard-codes a parser. A Resources/functions.php file provides legacy function shims.

Tech Stack - Pure PHP requiring PHP >= 8.1, twig/twig ^3.13|^4.0, and symfony/deprecation-contracts. The Markdown engines (league/commonmark, erusev/parsedown, michelf/php-markdown, league/html-to-markdown) are optional dev/runtime dependencies you install based on which adapter you use. Tested with symfony/phpunit-bridge.

Code Quality - Classes are final and single-purpose, the public surface is tiny, and error handling is explicit — for example the html_to_markdown filter throws a clear LogicException telling you to composer require league/html-to-markdown when the converter is missing. A functional and integration test suite with fixtures exercises the filters and adapters.

API Design - Extremely approachable: after registering the extension you write {{ content|markdown_to_html }} and you are done. The interface-plus-adapter design keeps the DX simple for common cases while leaving an escape hatch for custom parsers, and it mirrors the conventions of the wider Twig Extra family so it feels native to Twig users.