Markdown

Maizzle makes it easy to use Markdown in your email templates.

markdown-it is used and you can configure it either globally from your Environment config, or through Front Matter for each Template.

Attributes

Use attributes if you need the element wrapping your Markdown to be preserved:

src/templates/example.html

<div markdown>Using a `markdown` attribute</div>
<p md>You can also use the `md` attribute.</p>

Result:

<div>
  <p>Using a <code>markdown</code> attribute</p>
</div>
<p>You can also use the <code>md</code> attribute.</p>

Wrapping tag

Use the tag attribute to specify a tag name to wrap your Markdown with:

src/templates/example.html

<md tag="section">This Markdown will be _compiled_ to HTML</md>

Result:

<section>
  <p>This Markdown will be <em>compiled</em> to HTML</p>
</section>

Importing files

Already have some Markdown in a file? Simply include it:

src/templates/example.html

<md src="./README.md">
  # You'll see contents of README.md above this heading
</md>

Result:

<!-- contents of README.md here -->
<h1>You'll see contents of README.md above this heading</h1>

If you're including a file that will be used as an inline element and don't want the enclosing <p> tags, use the inline attribute:

src/templates/example.html

<p class="example">
  <markdown src="./example.md" inline>
    _Imported_
  </markdown>
</p>

Result:

<p class="example">
  <!-- Contents of ./example.md rendered to HTML -->
  <em>Imported</em>
</p>

GFM

GitHub Flavored Markdown is supported and the Tables and Strikethrough extensions are enabled by default.

Tables

Create tables with pipes | and hyphens -. Use hyphens to define each column's header, and pipes to separate each column.

src/templates/example.html

<markdown>
  | Markdown      | tables are    | cool  |
  | ------------- |:-------------:| -----:|
  | col 3 is      | right-aligned | $1600 |
  | col 2 is      | centered      |   $12 |
  | zebra stripes | are neat      |    $1 |
</markdown>

Strikethrough

Use two tildes ~~ to ~~~~strikethrough~~~~ text.

Configuration

You may configure how Markdown is rendered through the markdown config object:

config.js

module.exports = {
  markdown: {
    root: './', // A path relative to which markdown files are imported
    encoding: 'utf8', // Encoding for imported Markdown files
    markdownit: {}, // Options passed to markdown-it
    plugins: [], // Plugins for markdown-it
  }
}

Checkout the options for markdown-it and posthtml-markdownit.

Front Matter

You may override the global Markdown config from your Template's Front Matter.

src/templates/example.html

---
markdown:
  markdownit:
    linkify: true
---

<x-main>
  <md>
    https://example.com
  </md>
</x-main>

That will output:

<p><a href="https://example.com">https://example.com</a></p>

Disabling

Disable the markdown Transformer by setting it to false:

config.js

module.exports = {
  markdown: false
}

Plugins

There are over 300 plugins for markdown-it available on NPM! To use a plugin, npm install it first and then add it to config.js.

For example, imagine we installed markdown-it-emoji:

config.js

module.exports = {
  markdown: {
    plugins: [
      {
        plugin: require('markdown-it-emoji'),
        options: {} // Options for markdown-it-emoji
      }
    ]
  }
}

We can now use emojis in markdown:

src/templates/example.html

<md>
  You can use emojis :)
</md>

Result:

<p>You can use emojis 😃</p>

Escaping variables

If you're using expressions to render markdown from a variable that you have defined in your config like this:

config.js

module.exports = {
  data: {
    content: '> a markdown string'
  }
}

... you will need to use triple curly braces to output the unescaped content:

src/templates/example.html

<x-main>
  {{{ page.data.content }}}
</x-main>

This is required for things like blockquotes to work, otherwise > will be output as > and the blockquote will be rendered as a paragraph.