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 &copy; 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 flavor markdown-extra. With the other flavors the caret is treated as the first character of the link target, so [^1] becomes a link to 1.

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.