PostHTML configuration

Maizzle uses PostHTML for templating and transformations, and you can configure it or even register plugins that can further transform your HTML emails.

Options

PostHTML is configured under build.posthtml.options in your config.js.

directives

Type: Array
Default: []

You can configure the PostHTML parser to correctly process custom directives.

For example, you may tell it to ignore <?php ?> tags instead of treating them as HTML:

export default {
  posthtml: {
    options: {
      directives: [
        { name: '?php', start: '<', end: '>' },
      ]
    }
  }
}

xmlMode

Type: Boolean
Default: false

Enable xmlMode if you're using Maizzle to output XML content, and not actual HTML.

export default {
  posthtml: {
    options: {
      xmlMode: true,
    }
  }
}

decodeEntities

Type: Boolean
Default: false

Set this to true to have entities within the document decoded.

export default {
  posthtml: {
    options: {
      decodeEntities: true,
    }
  }
}

lowerCaseTags

Type: Boolean
Default: false

Set this to true to output all tags in lowercase. Works only when xmlMode is disabled.

export default {
  posthtml: {
    options: {
      lowerCaseTags: true,
    }
  }
}

lowerCaseAttributeNames

Type: Boolean
Default: false

Output all attribute names in lowercase.

export default {
  posthtml: {
    options: {
      lowerCaseAttributeNames: true,
    }
  }
}

recognizeCDATA

Type: Boolean
Default: false

Recognize CDATA sections as text even if the xmlMode option is disabled.

export default {
  posthtml: {
    options: {
      recognizeCDATA: true,
    }
  }
}

recognizeSelfClosing

Type: Boolean
Default: true

If enabled, self-closing tags will trigger the onclosetag event even if xmlMode is disabled.

Maizzle sets this to true to ensure self-closing tags like those of Components are rendered correctly.

export default {
  posthtml: {
    options: {
      recognizeSelfClosing: true,
    }
  }
}

sourceLocations

Type: Boolean
Default: false

If set to true, AST nodes will have a location property containing the start and end line and column position of the node.

export default {
  posthtml: {
    options: {
      sourceLocations: true,
    }
  }
}

recognizeNoValueAttribute

Type: Boolean
Default: true

If set to true, PostHTML will render attributes with no values exactly as they were written and will not add ="" to them.

export default {
  posthtml: {
    options: {
      recognizeNoValueAttribute: true,
    }
  }
}

singleTags

Type: Array<String|RegExp>
Default: []

Use the singleTags option to tell PostHTML to treat custom tags as self-closing.

export default {
  posthtml: {
    options: {
      singleTags: ['custom'],
      closingSingleTag: 'slash', // see docs below
    }
  }
}

You may then use the <custom /> tag as self-closing:

<custom name="opencounter" type="tracking" />

closingSingleTag

Type: String
Default: 'default'

Define the closing format for single tags.

By default it will not close self-closing tags that it knows about:

<img>
<p></p>

Available options:

tag

Will add a closing tag.

export default {
  posthtml: {
    options: {
      singleTags: ['custom'],
      closingSingleTag: 'tag',
    }
  }
}

<custom></custom>

slash

Will add a closing tag.

export default {
  posthtml: {
    options: {
      singleTags: ['custom'],
      closingSingleTag: 'slash',
    }
  }
}

<custom />

quoteAllAttributes

Type: Boolean
Default: true

Disable if you want to remove quotes on all attributes

export default {
  posthtml: {
    options: {
      quoteAllAttributes: false,
    }
  }
}

<img src=example.jpg>

replaceQuote

Type: Boolean
Default: true

Replaces quotes in attribute values with &quote;.

export default {
  posthtml: {
    options: {
      replaceQuote: false,
    }
  }
}

<!-- `true` (default) -->
<img src="<?php echo $foo[&quote;bar&quote;] ?>">

<!-- `false` -->
<img src="<?php echo $foo["bar"] ?>">

quoteStyle

Type: Number
Default: 2

Specify the attribute value quotes style.

export default {
  posthtml: {
    options: {
      quoteStyle: 1,
    }
  }
}

<!-- `2` (double quotes, default) -->
<img src="example.png" onload="testFunc("test")">

<!-- `1` (single quotes) -->
<img src='example.png' onload='testFunc("test")'>

<!-- `0` (based on attribute value) -->
<img src="example.png" onload='testFunc("test")'>

Plugins

Type: Array
Default: []

Register any PostHTML plugins that you would like to use, in the plugins array.

You may register plugins to run either before all other plugins, or after all other plugins, by using the before and after keys.

import spaceless from 'posthtml-spaceless'

export default {
  posthtml: {
    plugins: {
      before: [
        spaceless()
      ]
    }
  }
}

Custom plugins

You may write your own PostHTML plugins, right in your Maizzle config.js file.

For example, here's a plugin that adds a random number to all <img> src URLs:

export default {
  posthtml: {
    plugins: {
      after: [
        (() => tree => {
          const process = node => {
            if (node.tag === 'img' && node.attrs?.src) {
              const randomNumber = Math.floor(Math.random() * 10 ** 16).toString().padStart(16, '0')
              node.attrs.src = node.attrs.src + `?v=${randomNumber}`
            }

            return node
          }

          return tree.walk(process)
        })()
      ]
    }
  }
}

Built-in plugins

Maizzle already uses the following PostHTML plugins internally:

• posthtml-mso
• posthtml-base-url
• posthtml-content
• posthtml-component
• posthtml-extra-attributes
• posthtml-markdownit
• posthtml-postcss-merge-longhand
• posthtml-remove-attributes
• posthtml-safe-class-names
• posthtml-url-parameters