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.

Tags

There are two tags that you can use to add Markdown to your emails:

<markdown>This Markdown will be **compiled** to HTML</markdown>
<md>A _shorter_ version of the `markdown` tag.</md>

Result:

<p>This Markdown will be <strong>compiled</strong> to HTML</p>
<p>A <em>shorter</em> version of the <code>markdown</code> tag.</p>

Attributes

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

<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:

<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:

<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:

<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.

<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:

export default {
  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.

---
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:

export default {
  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:

import mdEmoji from 'markdown-it-emoji'

export default {
  markdown: {
    plugins: [
      {
        plugin: mdEmoji,
        options: {} // Options for markdown-it-emoji
      }
    ]
  }
}

We can now use emojis in markdown:

<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:

export default {
  data: {
    content: '> a markdown string'
  }
}

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

<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.

API

You may use the Markdown Transformer in your application.

import { markdown } from '@maizzle/framework'

const options = {/* posthtml-markdownit options */}
const posthtmlOptions = {/* posthtml options */}

const html = await markdown('### Heading 3', options, posthtmlOptions)

If you only need some parts of your string to be parsed as Markdown, you can use the manual option and then wrap the Markdown content in <md> tags:

const html = await markdown(
  `
  <section>
    <h2>Code sample</h2>
    <md>`const foo = 'bar'`</md>
  <section>
  `,
  { manual: true },
)