remark-containers

This remark plugin provides parsing for containers in your markdown.

Default Syntax

Containers begin with ::: [noparse] {HTML Element Name} [optional list of classes] on a new line, and end with ::: on a new line. Container markers may be indented by up to 2 spaces.

For example:

::: aside class-one class-two
# Header One

With container contents. 
:::

renders as:

<aside class="class-one class-two">
  <h1>Header One</h1>
  <p>With container contents.</p>
</aside>

Containers may be nested

For example:

::: div outer
# Header One

Outer contents.

  ::: div inner
  Inner contents.
  :::

More outer contents.
::: 

renders as:

<div class="outer">           
  <h1>Header One</h1>         
  <p>Outer contents.</p>      
  <div class="inner">         
    <p>Inner contents.</p>    
  </div>                      
  <p>More outer contents.</p> 
</div>                        

noparse stops processing of the container contents and instead treats it as raw text.

For example:

::: noparse div outer
# Header One

Outer contents.

 ::: div inner
 Inner contents. 
 :::

More outer contents.
::: 

renders as:

<div class="outer">           
# Header One
Outer contents.
::: div inner
Inner contents. 
:::
More outer contents.
</div>                        

Installation

npm install remark-containers

Usage

const unified = require('unified')
const parse = require('remark-parse')
const containers = require('remark-containers')
const stringify = require('rehype-stringify')
const remark2rehype = require('remark-rehype')

unified()
  .use(parse)
  .use(containers)
  .use(remark2rehype)
  .use(stringify)

Options

Passing an options object allows full control over the resulting mdast.

.use(containers, {
  default: true, 
  custom: [{
    type: 'callout',
    element: 'article',
    transform: function(node, config, tokenize) {
      node.data.hProperties = {
          className: config || 'left'
      }
    }
    }, {
        type: 'quote',
        element: 'aside',
        transform: function(node, config, tokenize) {
          var words = tokenizeWords.parse(config)

          node.data.hProperties = {
              className: `quoted ${words.shift()}`
          }
          node.children.push({
              type: 'footer',
              data: {
                hName: 'footer'
              },
              children: tokenize(words.join(' '))
          })
        }
    }
  ]
})

default

When true the default syntax will also be enabled.

custom

An array of custom container configurations.

type

A single word string identifying the type of this container. Any markdown of the form ::: {type} will use this custom transform.

element

The html element name to use for the container. Default 'div'.

transform(node, config, tokenize)

A function to manipulate the mdast node.

node

The mdast node for this container.

config

The string after ::: type until the end of the line. Can be used to configure how the transform operates.

tokenize

A function(value): mdastNode you can use to tokenize an inline markdown string, if needed.

Feedback

Bugs & feedback.

License

MIT © Dan Behlings