Book: document markdown filter

1 files changed, 25 insertions, 0 deletions

diff --git a/book/src/filters.md b/book/src/filters.md
index 9fb71c5..f8e30a7 100644
--- a/book/src/filters.md
+++ b/book/src/filters.md
@@ -38,6 +38,7 @@ but are disabled by default. Enable them with Cargo features (see below for more
 
 * **[Optional / feature gated filters][#optional-filters]:**  
   [`json|tojson`][#json],
+  [`markdown`][#markdown],
   [`yaml`][#yaml]
 
 * **[Custom filters][#custom-filters]**
@@ -369,6 +370,30 @@ Ugly: <script>var data = "{{data|json}}";</script>
 Ugly: <script>var data = '{{data|json|safe}}';</script>
 ```
 
+### `markdown`
+[#markdown]: #markdown
+
+Enabling the `markdown` feature will enable the use of the `markdown` filter.
+This will render a value using a [GitHub flavored CommonMark](https://docs.rs/comrak/0.12.*/comrak/) syntax.
+By default the extensions “autolink”, “strikethrough”, “tagfilter”, and “table” are enabled.
+Any raw HTML gets escaped.
+
+```jinja
+{{ "**<i>Hello</i>, world!**"|markdown }}
+```
+
+Output:
+
+```html
+<p><strong>&lt;i&gt;Hello&lt;/i&gt;, world!</strong></p>
+```
+
+You can change the default settings by supplying [custom options][ComrakRenderOptions], e.g. to enable unsafe raw HTML.
+You can find a usage example in our [unit tests][markdown-tests].
+
+[ComrakRenderOptions]: https://docs.rs/comrak/0.12.*/comrak/struct.ComrakRenderOptions.html
+[markdown-tests]: https://github.com/djc/askama/blob/5748c357d435b24848d1571df010d777859fede9/testing/tests/markdown.rs#L36-L75
+
 ### `yaml`
 [#yaml]: #yaml