Book: document markdown filter

book/src/filters.md

@@ -16,9 +16,38 @@ is passed to the next.
 Askama has a collection of built-in filters, documented below, but can also include custom filters. Additionally, the `json` and `yaml` filters are included in the built-in filters,
 but are disabled by default. Enable them with Cargo features (see below for more information).
 
+**Table of contents**
+
+* **[Built-in filters][#built-in-filters]:**  
+  [`abs`][#abs],
+  [`capitalize`][#capitalize],
+  [`center`][#center],
+  [`escape|e`][#escape],
+  [`filesizeformat`][#filesizeformat],
+  [`format`][#format],
+  [`indent`][#indent],
+  [`join`][#join],
+  [`linebreaks`][#linebreaks],
+  [`linebreaksbr`][#linebreaksbr],
+  [`lower|lowercase`][#lower],
+  [`safe`][#safe],
+  [`trim`][#trim],
+  [`truncate`][#truncate],
+  [`upper|uppercase`][#upper],
+  [`wordcount`][#wordcount]
+
+* **[Optional / feature gated filters][#optional-filters]:**  
+  [`json|tojson`][#json],
+  [`markdown`][#markdown],
+  [`yaml`][#yaml]
+
+* **[Custom filters][#custom-filters]**
+
 ## Built-In Filters
+[#built-in-filters]: #built-in-filters
 
 ### abs
+[#abs]: #abs
 
 Returns the absolute value.
 
@@ -33,6 +62,7 @@ Output:
 ```
 
 ### capitalize
+[#capitalize]: #capitalize
 
 Capitalize a value. The first character will be uppercase, all others lowercase:
 
@@ -47,6 +77,7 @@ Hello
 ```
 
 ### center
+[#center]: #center
 
 Centers the value in a field of a given width:
 
@@ -60,6 +91,7 @@ Output:
 ```
 
 ### escape | e
+[#escape]: #escape--e
 
 Escapes HTML characters in strings:
 
@@ -96,6 +128,7 @@ Escape <>&
 [`escape = "none"`]: creating_templates.html#the-template-attribute
 
 ### filesizeformat
+[#filesizeformat]: #filesizeformat
 
 Returns adequate string representation (in KB, ..) of number of bytes:
 
@@ -109,6 +142,7 @@ Output:
 ```
 
 ### format
+[#format]: #format
 
 Formats arguments according to the specified format.
 
@@ -121,6 +155,7 @@ All arguments are passed through to the `format!()` macro by the Askama code gen
 ```
 
 ### indent
+[#indent]: #indent
 
 Indent newlines with width spaces.
 
@@ -137,6 +172,7 @@ hello
 ```
 
 ### join
+[#join]: #join
 
 Joins iterable into a string separated by provided argument.
 
@@ -155,6 +191,7 @@ foo, bar, bazz
 ```
 
 ### linebreaks
+[#linebreaks]: #linebreaks
 
 Replaces line breaks in plain text with appropriate HTML.
 
@@ -171,6 +208,7 @@ Output:
 ```
 
 ### linebreaksbr
+[#linebreaksbr]: #linebreaksbr
 
 Converts all newlines in a piece of plain text to HTML line breaks.
 
@@ -185,6 +223,7 @@ hello<br />world<br /><br />from<br />askama
 ```
 
 ### paragraphbreaks
+[#paragraphbreaks]: #paragraphbreaks
 
 A new line followed by a blank line becomes `<p>`, but, unlike `linebreaks`, single new lines are ignored and no `<br/>` tags are generated.
 
@@ -203,6 +242,7 @@ Output:
 ```
 
 ### lower | lowercase
+[#lower]: #lower--lowercase
 
 Converts to lowercase.
 
@@ -217,6 +257,7 @@ hello
 ```
 
 ### safe
+[#safe]: #safe
 
 Marks a string (or other Display type) as safe. By default all strings are escaped according to the format.
 
@@ -231,6 +272,7 @@ Output:
 ```
 
 ### trim
+[#trim]: #trim
 
 Strip leading and trailing whitespace.
 
@@ -245,6 +287,7 @@ hello
 ```
 
 ### truncate
+[#truncate]: #truncate
 
 Limit string length, appends '...' if truncated.
 
@@ -260,6 +303,7 @@ he...
 ```
 
 ### upper | uppercase
+[#upper]: #upper--uppercase
 
 Converts to uppercase.
 
@@ -274,6 +318,7 @@ HELLO
 ```
 
 ### wordcount
+[#wordcount]: #wordcount
 
 Count the words in that string.
 
@@ -288,6 +333,7 @@ Output:
 ```
 
 ## Optional / feature gated filters
+[#optional-filters]: #optional--feature-gated-filters
 
 The following filters can be enabled by requesting the respective feature in the Cargo.toml
 [dependencies section](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html), e.g.
@@ -298,6 +344,7 @@ askama = { version = "0.11.0", features = "serde-json" }
 ```
 
 ### `json` | `tojson`
+[#json]: #json--tojson
 
 Enabling the `serde-json` feature will enable the use of the `json` filter.
 This will output formatted JSON for any value that implements the required
@@ -323,7 +370,32 @@ 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
 
 Enabling the `serde-yaml` feature will enable the use of the `yaml` filter.
 This will output formatted YAML for any value that implements the required
@@ -333,8 +405,8 @@ This will output formatted YAML for any value that implements the required
 {{ foo|yaml }}
 ```
 
-
 ## Custom Filters
+[#custom-filters]: #custom-filters
 
 To define your own filters, simply have a module named filters in scope of the context deriving a `Template` impl.