Markdown
Pages with the file extension .md or .markdown are converted to HTML by the markdown system
plugin. The plugin is based on the library
league/commonmark, which implements the
CommonMark specification.
The default flavor commonmark implements the specification only. Constructs such as tables,
task lists and footnotes require a different flavor, see Markdown flavor
below.
Configuration
The plugin is configured under plugins.markdown in the configuration file site/config/main.php.
These are the defaults:
return [
'plugins' => [
'markdown' => [
'enableTwigFilter' => true,
'enableTwigFunction' => true,
'flavor' => 'commonmark',
'commonmark' => [
'html_input' => 'allow',
'allow_unsafe_links' => true,
],
],
],
];
| Option | Default | Description |
|---|---|---|
enableTwigFilter |
true |
Registers the Twig filter markdown |
enableTwigFunction |
true |
Registers the Twig function markdown() |
flavor |
commonmark |
The markdown dialect, see below |
commonmark |
see above | Options for the CommonMark environment |
Markdown flavor
The option flavor selects the set of CommonMark extensions. An unknown value falls back to
commonmark without an error message.
| Flavor | Description |
|---|---|
commonmark |
The CommonMark specification. This is the default. |
gfm |
GitHub Flavored Markdown: adds autolinks, tables, strikethrough, task lists and filtered raw HTML. |
markdown-extra |
Markdown Extra features on top of CommonMark: attributes, definition lists, footnotes, strikethrough, tables and task lists. |
To use GitHub Flavored Markdown, for example so that tables and task lists work out of the box:
return [
'plugins' => [
'markdown' => [
'flavor' => 'gfm',
],
],
];
Parser options
Every option of league/commonmark can be used in plugins.markdown.commonmark. The values are
passed to the parser environment unchanged. A complete reference is available in the
CommonMark documentation.
Herbie sets html_input to allow and allow_unsafe_links to true by default, as shown above.
Further options such as max_nesting_level, the renderer.* options or the options of the
gfm and markdown-extra extensions are described in the CommonMark reference.
Please note that a misspelled option name is silently ignored, while an invalid value throws an exception.
Restricting raw HTML
Raw HTML in markdown pages is rendered as it is by default. If the content comes from untrusted
authors, this is a security risk. The option html_input allows to restrict it:
return [
'plugins' => [
'markdown' => [
'commonmark' => [
'html_input' => 'escape',
'allow_unsafe_links' => false,
],
],
],
];
Twig filter and function
In addition to page content, the parser is available in Twig templates as filter and as function.
{{ '# A heading'|markdown }}
{{ markdown('# A heading') }}
Both are registered by default and can be disabled with enableTwigFilter and
enableTwigFunction.
Supported constructs per flavor
The following table shows which markdown constructs are available in each flavor.
| Construct | commonmark |
gfm |
markdown-extra |
|---|---|---|---|
| Pipe tables | plain text | table | table |
| Task lists | plain text | checkbox | checkbox |
| Strikethrough | plain text | <del> |
<del> |
| Footnotes | link | link | footnotes |
| Definition lists | plain text | plain text | <dl> |
Attributes {: #id } |
plain text | plain text | applied |
| Bare URLs | plain text | linked | plain text |
| HTML entities | decoded | decoded | decoded |
| Raw HTML block | preserved | preserved | preserved |
Two details are worth pointing out:
- HTML entities such as
©are decoded and output as the character©. This rarely changes what the visitor sees, but it changes the generated markup. - Footnotes with the
[^1]syntax are only supported by the flavormarkdown-extra. With the other flavors the caret is treated as the first character of the link target, so[^1]becomes a link to1.
Raw HTML blocks
Raw HTML blocks end at the first empty line according to the CommonMark specification. Herbie protects such blocks before parsing, so a block spread over several paragraphs still renders as HTML:
<div>
Paragraph 1
Paragraph 2
</div>
Indented code samples that contain HTML remain code blocks.