posthtml-markdownit

Transform Markdown to HTML

Introduction

This PostHTML plugin compiles Markdown to HTML using markdown-it.

Before:

<markdown>
  # Heading 1
  ---

  Paragraph with some text

  _Italic_
  **Bold**

  - List item 1
  - List item 2
  - List item 3
</markdown>

After:

<h1>Heading 1</h1>
<hr>
<p>Paragraph with some text</p>
<p>
  <em>Italic</em>
  <strong>Bold</strong>
</p>
<ul>
  <li>List item 1</li>
  <li>List item 2</li>
  <li>List item 3</li>
</ul>

Install

npm i -D posthtml posthtml-markdownit

Usage

import posthtml from 'posthtml'
import markdown from 'posthtml-markdownit'

posthtml([
  markdown()
])
  .process('<markdown># Test</markdown>')
  .then(result => console.log(result.html))

// <h1>Test</h1>

Importing files

You can import and render Markdown files:

Before:

<markdown src="./README.md">
  # Imported
</markdown>

After:

<!-- Here be the contents of README.md, as HTML -->
<h1>Imported</h1>

Syntax

Tags

Both <markdown> and <md> tags are supported.

Before:

<md>
  # Heading 1
</md>

After:

<h1>Heading 1</h1>

By default, the custom tags like <md> are replaced with the compiled Markdown. See the tag attribute if you need a wrapping tag around your Markdown content.

Attributes

You can also use the markdown or md attributes on an HTML element:

Before:

<div md>
  # Heading 1
</div>

After:

<h1>Heading 1</h1>

tag

You can use a tag attribute to wrap the resulting markup in a tag:

Before:

<md tag="section">
  # Heading 1
</md>

After:

<section>
  <h1>Heading 1</h1>
</section>

inline

You can mark the content to be rendered inline. This is helpful if you're including a file that will be used as an inline element and don't want the enclosing p tags.

Before:

<div class="example">
  <markdown src="./example.md" inline>
    Imported
  </markdown>
</div>

After:

<p class="example">Imported</p>

Instead of:

<div class="example">
  <p>Imported</p>
</div>

Options

root

Type: string
Default: ./

A path relative to which Markdown files will be imported.

encoding

Type: string
Default: utf8

Encoding for imported Markdown files.

markdownit

Type: object
Default: {}

Options passed to the markdown-it library. See the available options.

plugins

Type: array
Default: []

Plugins for markdown-it.

Example:

import {light as emoji} from 'markdown-it-emoji'

markdown({
  plugins: [{
    plugin: emoji,
    options: {} // Options for markdown-it-emoji
  }]
})