Markdown

Help texts, release notes and content kept in a database are easier to write as Markdown. {markdown} writes what it wraps as HTML: the content renders first, so fields and tags in it resolve, and the result is then read as Markdown. The text is dedented first, so the block can be indented along with the template around it.

PHP
fragments/markdown_1.php HTML
fragments/markdown_1.pad Result

PHP fragments/markdown_1.php	HTML fragments/markdown_1.pad	Result
`<?php $version = '2.1'; ?>`	`{markdown} ## Release notes for {$version} - Faster first render - Lists can be nested: 1. one 2. two > See [the manual](?index) for the rest. {/markdown}`	Release notes for 2.1 Faster first render Lists can be nested: one two See the manual for the rest.

<?php

  $version = '2.1';

?>

{markdown}
  ## Release notes for {$version}

  - **Faster** first render
  - Lists can be *nested*:
    1. one
    2. two

  > See [the manual](?index) for the rest.
{/markdown}

Release notes for 2.1

Faster first render
Lists can be nested:
1. one
2. two

See the manual for the rest.

The markdown pipe

A value - a post body from the database - goes through the markdown pipe, or is given to the tag as its parameter: {markdown $post.body}. The HTML it makes is safe by construction, so a field whose last pipe is markdown skips the sanitize chain that would escape the markup again.

PHP fragments/markdown_2.php	HTML fragments/markdown_2.pad	Result
<?php $post = [ 'body' => "Written by a visitor: <script>alert(1)</script> and `{php:getcwd}`" ]; ?>	`{$post.body \| markdown}`	Written by a visitor: <script>alert(1)</script> and `{php:getcwd}`

What is safe

Raw HTML in the text is escaped, not passed on. The html option of the tag lets the template author's own markup through; the pipe has no such form.
A link or image whose URL names a scheme other than http, https, mailto, ftp or tel - javascript:, data: - keeps only its text.
The HTML made from a value stays a value: PAD tags written in a post are shown, never run.
Braces in the template's own Markdown - code samples - need the ignore option: {markdown ignore}.

The built-in renderer is a CommonMark subset: headings, paragraphs, emphasis, code spans and code blocks, lists, links, images, block quotes and rules. Reference-style links, tables and footnotes are not supported.