Markdown

Maizzle supports Markdown in your email templates.

Marked.js is used together with PostHTML and you can fully configure it, either 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:

<div markdown>This Markdown will be **compiled** to HTML</div>
<p md>There's also a _shorter_ version of the tag above.</p>

Result:

<div>
  <p>This Markdown will be <strong>compiled</strong> to HTML</p>
</div>
<p>There's also a <em>shorter</em> version of the tag above.</p>

Importing files

Already have Markdown somewhere in a file? Import it with Nunjucks:

<md>
  {% include 'post.md' %}
</md>

Nesting

You can even nest Markdown inside child elements:

<body markdown>
  <div>

    | Head | row |
    |------|-----|
    | Data | row |

  </div>
</body>

Nesting requires extra empty lines around Markdown, like in the <div> above.

GFM

Marked supports GitHub Flavored Markdown, and it's enabled by default in Maizzle.

Config

Here's how Marked.js is configured in Maizzle:

// config.js
module.exports = {
  markdown: {
    baseUrl: null,
    breaks: false,
    gfm: true,
    headerIds: false,
    headerPrefix: '',
    highlight: null,
    langPrefix: 'language-',
    mangle: true,
    pendantic: false,
    sanitize: false,
    sanitizer: null,
    silent: false,
    smartLists: false,
    smartypants: false,
    tables: true,
    xhtml: false
  },
  // ...
}

For an explanation of what each option does, please see the Marked.js docs ↗

Front Matter

You can override the base Markdown config from your Template's Front Matter. Need a baseUrl for Markdown links, or to enable headerIds for a particular Template?

No problem:

---
title: Overriding the default Markdown config
markdown:
  headerIds: true
  baseUrl: https://github.com
---

{% block template %}
  ...
{% endblock %}

When using headerIds, you need to add a whitelist pattern to config.removeUnusedCSS (otherwise they'll be removed).

JavaScript is not supported in Front Matter, so you can't use highlight, renderer, or sanitizer here.

Gotchas

There are some situations where Markdown might not work as expected, or requires some additional work on your side.

Unclosed Tags

Because Maizzle uses cheerio in some of its Transformers that run after the Markdown Transformer, something like this:

<md>`<div>`</md>

... will be compiled to:

<p><code><div></div></code></p>

Basically, cheerio will automatically close any unclosed tags.

Classes

If you have fenced code blocks like this in your Markdown:

```html
  <div>Lorem ipsum</div>
‌```

... then config.markdown.langPrefix needs to be whitelisted inside removeUnusedCSS:

// config.production.js
module.exports = {
  cleanup: {
    removeUnusedCSS: {
      enabled: true,
      whitelist: ['.language-*'],
    },
    // ...
  }
}

IDs

When using the headerIds option:

// config.js
module.exports = {
  markdown: {
    headerIds: true,
    // ...
  },
}

... you also need to whitelist IDs with email-comb:

// config.production.js
module.exports = {
  cleanup: {
    removeUnusedCSS: {
      enabled: true,
      whitelist: ['.language-*', '#*'],
    },
    // ...
  }
}