remark-custom-container

remarkjs parser plugin for custom directive (compatible with new parser in remark. see #536)

Note This plugin is highly inspired by vuepress-plugin-container.

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

Syntax

Container described with :::[space]{class name}[space]{container title} and :::.

example:

::: className Custom Title

Container Body

:::

will be rendered as follows

<div class="remark-container className">
  <div class="remark-container__title">
    Custom Title
  </div>
  Container Body
</div>

Install

$ npm install remark-custom-container

Usage

import remark from "remark";
import remark2rehype from "remark-rehype";
import stringify from "rehype-stringify";

import container from "remark-custom-container";

const html = await remark()
  .use(container)
  .use(remark2rehype)
  .use(stringify);

Options

use(container, {
  className: string, // optional, default to "remark-container",
  containerTag: string, // optional, default to "div"
  titleElement: Record<string, unknown> | null, // optional, default to { className: string[] }
  additionalProperties: (className?: string, title?: string) => Record<string, unknown>, // optional, default to undefined
})

className is an option to provide custom className other than remark-container.

containerTag is an option to provide custom HTML tag for the container other than div.

titleElement is an option to construct custom inner title div element. The default is pre-defined { className: string[] }, so the plugin is going to add an inner title div element as a default. You can provide an object in order to set additional properties for the inner title div element. If you set null, the plugin is going to remove the inner title div element like below.

<div class="remark-container className">
  Container Body
</div>

additionalProperties is an option to set additional properties for the custom container. It is a callback function that takes the className and the title as optional arguments and returns the object which is going to be used for adding additional properties into the container.

example:

::: warning My Custom Title

my paragraph

:::

use(container, {
  className: "remark-custom-classname",
  containerTag: "article",
  titleElement: null,
  additionalProperties: (className, title) => {
    title,
    ["data-type"]: className?.toLowerCase(),
  }
})

is going to produce the container below:

<article class="remark-custom-classname warning" title="My Custom Title" data-type="warning">
  <p>my paragraph</p>
</article>

Note : The containerTag is not prefered to be a span or similar, if there is an inner title div element. This may cause a problem because of a div element under a span element.