posthtml-markdownit

posthtml-markdownit

Transform markdown using markdown-it

Introduction

This PostHTML plugin converts 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

const posthtml = require('posthtml')
const markdown = require('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:

<!-- 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 tags are removed. 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 are imported.

encoding

Type: string
Default: utf8

Encoding for imported Markdown files.

markdownit

Type: object
Default: {}

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

plugins

Type: array
Default: []

Plugins for markdown-it.

Example:

const {light: emoji} = require('markdown-it-emoji')

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