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
  optionsByClassName: Array<{
    selector: string, // required, classname of the container
    containerTag?: string, // optional, default to "div"
    titleTag?: string, // optional, default to "div"
    titleElement?: Record<string, unknown> | null, // optional, default to { className: string[] }
    additionalProperties?: (className?: string, title?: string) => Record<string, unknown>,
  }>,
})

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>

optionsByClassName is an option for setting tags and the like differently for each className. You can insert the class name into the selector and specify it similarly to the existing options. If the existing options and optionsByClassName overlap, the items in optionsByClassName will be applied first.

example:

::: details My Custom Details

markdown content

:::

use(container, {
  optionsByClassName: [
    {
      selector: "details",
      containerTag: "details",
      titleTag: "summary",
      titleElement: {
        className: ["summary-title"],
      },
    },
  ],
});

is going to produce the container below:

<details class="remark-container details">
  <summary class="summary-title">My Custom Details</summary>
  <p>markdown content</p>
</details>

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.