From 36cd35dff482d46242354faa1e137f43a0a34670 Mon Sep 17 00:00:00 2001
From: Fabien Potencier <fabien@potencier.org>
Date: Fri, 5 Jun 2026 21:50:30 +0200
Subject: [PATCH] Document how to customize the markdown_to_html converter

---
 doc/filters/markdown_to_html.rst | 34 ++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/doc/filters/markdown_to_html.rst b/doc/filters/markdown_to_html.rst
index 886cda4d4..780f0112b 100644
--- a/doc/filters/markdown_to_html.rst
+++ b/doc/filters/markdown_to_html.rst
@@ -77,3 +77,37 @@ You can also use the filter on an included file or a variable:
     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``), and ``ErusevMarkdown`` (``erusev/parsedown``). 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``)::
+
+    use Twig\Extra\Markdown\ErusevMarkdown;
+
+    $parsedown = new \ParsedownExtra();
+    $parsedown->setSafeMode(true);
+
+    $markdown = new ErusevMarkdown($parsedown);
+
+When using ``twig/extra-bundle``, register your converter as the
+``twig.markdown.default`` service to make it the one used by the filter:
+
+.. code-block:: yaml
+
+    # 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.