{markdown}

Renders its content, or the value of its parameter, as Markdown and writes the HTML.

Text and formatting Either form

Syntax 

{markdown $text}
{markdown} ... {/markdown}
{markdown html} ... {/markdown}
{markdown ignore} ... {/markdown}

Parameters

text
In the single form: the Markdown to write, as the markdown pipe reads a value.

Options

html
Bare option: let the author's own raw HTML through - inline tags, and a block-level element or comment at the start of a line up to the next blank line. Without it raw HTML is escaped.
ignore
Bare option: the braces in the content are text, not tags - for code samples in the Markdown.

Description

As a pair, {markdown} renders its content first - its fields and tags resolve like anywhere else - and then reads the result as Markdown and writes the HTML. The text is dedented first, so a block indented along with the template does not turn into a code block. With a parameter instead, {markdown $post.body} writes the value of the parameter, the way the markdown pipe does.

The converter is built in (lib/markdown.php), a CommonMark subset: ATX and setext headings, paragraphs, emphasis and strong emphasis, code spans, fenced code blocks (with a language- class) and indented ones, bullet and ordered lists (nested, tight or loose, with a start number), links, images, autolinks, block quotes, thematic breaks, hard line breaks and backslash escapes. Reference-style links, tables and footnotes are not supported.

Safety

Raw HTML in the text is escaped, and a link or image whose address names a scheme other than http, https, mailto, ftp or tel - javascript:, data: - keeps only its text. The bare html option lets the author's own markup through; use it only for text the application wrote. The HTML made from a value stays a value: a {php:getcwd} in a post is shown, not run.

Braces

Because the content is rendered before it is read as Markdown, a { in it starts a tag. A code sample with braces needs the ignore option, which keeps the whole content as text - fields included. A pair that is never closed, and the single form without a value, are strict errors.

Examples

Markdown around fields

The fields resolve first, then the text is read as Markdown - the indent of the template does not count.

Templateexamples/markdown/1-pair.pad 
{set $version = '3.0'}
{markdown}
  ### Release notes for {$version}

  - **Faster** first render
  - Charts in *every* page
  - See [all tags](?names) for more

  > Upgrade by copying the files.
{/markdown}
Resultopen alone

Release notes for 3.0

  • Faster first render
  • Charts in every page
  • See all tags for more

Upgrade by copying the files.

A value as Markdown

The single form writes the value of its parameter; raw HTML in it is escaped and a javascript: link loses its address.

Templateexamples/markdown/2-value.pad 
{markdown $comment}
PHPexamples/markdown/2-value.php 
<?php

  $comment = "Thanks for the **quick** fix!\n\n"
           . "It works in <b>Firefox</b> too - see [the issue](https://example.com/issues/42) "
           . "and [this link](javascript:alert(1)).";

?>
Resultopen alone

Thanks for the quick fix!

It works in <b>Firefox</b> too - see the issue and this link.

A code sample with braces

With ignore the braces in the fenced block are text, so the template sample shows as written.

Templateexamples/markdown/3-ignore.pad 
{markdown ignore}
  Loop over the rows with a pair:

  ```pad
  {orders}
    <li>{$number}</li>
  {/orders}
  ```
{/markdown}
Resultopen alone

Loop over the rows with a pair: 

{orders}
  <li>{$number}</li>
{/orders}

See also

  • {highlight} Colours source code on the server - PAD, PHP, HTML, CSS, JavaScript, JSON, YAML, SQL or shell - with optional line numbers and marked lines.
  • {collection} Reads a folder of Markdown files from _content/ and repeats its content once per file, the front matter as fields.
  • {ignore} Keeps PAD from reading the braces in its content as tags - for inline JavaScript, CSS, JSON and code samples.
  • {toc} A table of contents of the page from its own rendered headings, nested and linked - filled in once the page has rendered.