Skip to main content

@mdit/plugin-container


Plugin for creating block-level custom containers.

Usage

TS
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

:::
`);

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 some styles and:

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:

::: hint Here is a Hint
:::

::: hint

Here is a **hint** for you!

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

:::

Here is a hint

Hint

Here is a hint for you!

  • Hint 1
    • Hint 1.1
    • Hint 1.2
  • Hint 2