@mdit/plugin-container

Plugin for creating block-level custom containers.

Usage

import MarkdownIt from "markdown-it";
import { container } from "@mdit/plugin-container";

const mdIt = MarkdownIt().use(container, {
  // your options, name is required
  name: "warning",
});

mdIt.render(`
::: warning

Warning Text

:::
`);

const MarkdownIt = require("markdown-it");
const { container } = require("@mdit/plugin-container");

const mdIt = MarkdownIt().use(container, {
  // your options, name is required
  name: "warning",
});

mdIt.render(`
::: warning

Warning Text

:::
`);

Syntax

With this plugin you can create block containers like:

::: warning
_here be dragons_
:::

and specify how they should be rendered. If no renderer defined, <div> with container name class will be created:

<div class="warning">
  <em>here be dragons</em>
</div>

Markup is the same as for fenced code blocks. However by default the plugin use another character as marker and content is rendered as markdown markup by plugin.

Nesting and escaping

Nestings can be done by increasing marker number of outer container:
```
:::: warning
Warning contents...
::: details
Some details
:::
::::
```
will be
Warning
Warning contents...
Details
Some details
Escaping can be done by adding \ to escape the marker:
```
\::: warning

:::
```
will be
::: warning
:::

Options

interface MarkdownItContainerOptions {
  /**
   * Container name
   */
  name: string;

  /**
   * Container marker
   *
   * @default ":"
   */
  marker?: string;

  /**
   * Validate whether it should be regarded as this container type
   *
   * @param params the content after the marker
   * @param markup marker character
   * @returns is this container type or not
   *
   * @default params.trim().split(" ", 2)[0] === name
   */
  validate?: (params: string, markup: string) => boolean;

  /**
   * Opening tag render function
   */
  openRender?: RenderRule;

  /**
   * Closing tag render function
   */
  closeRender?: RenderRule;
}

Demo

Hint container

With the following code and some styles:

md.use(container, {
  name: "hint",
  openRender: (tokens, index, _options) => {
    const info = tokens[index].info.trim().slice(4).trim();

    return `<div class="custom-container hint">\n<p class="custom-container-title">${
      info || "Hint"
    }</p>\n`;
  },
});

You can write a hint like this:

Here is a Hint

Hint

Here is a hint for you!

Hint 1
- Hint 1.1
- Hint 1.2
Hint 2

::: hint Here is a Hint
:::

::: hint

Here is a **hint** for you!

- Hint 1
  - Hint 1.1
  - Hint 1.2
- Hint 2

:::