@md-plugins/md-plugin-containers

A Markdown-It plugin that provides custom container support for enhanced Markdown rendering. Containers allow you to create stylized blocks with custom rendering logic, ideal for notes, warnings, callouts, and other visual elements.

Features

• Define custom containers with specific classes or components.
• Add titles to containers for better context (e.g., "Warning", "Note").
• Supports flexible rendering logic for different container types.
• Compatible with Markdown-It environments for additional customization.

Installation

Install the plugin via your preferred package manager:

# with pnpm:
pnpm add @md-plugins/md-plugin-containers
# with bun:
bun add @md-plugins/md-plugin-containers
# with Yarn:
yarn add @md-plugins/md-plugin-containers
# with npm:
npm install @md-plugins/md-plugin-containers

Usage

Basic Setup

import MarkdownIt from 'markdown-it'
import { containersPlugin } from '@md-plugins/md-plugin-containers'
import container from 'markdown-it-container'
import type {
  ContainerDetails,
  CreateContainerFn,
  Container,
  ContainerOptions,
} from '@md-plugins/md-plugin-containers'

const md = new MarkdownIt()

  const containers: ContainerDetails[] = [
    { type: 'tip', defaultTitle: 'TIP' },
    { type: 'warning', defaultTitle: 'WARNING' },
    { type: 'danger', defaultTitle: 'WARNING' },
    { type: 'details', defaultTitle: 'Details' },
  ]

const createContainer: CreateContainerFn = (
  container: Container,
  containerType: string,
  defaultTitle: string,
  md: MarkdownIt,
): [Container, string, ContainerOptions] => {
  const containerTypeLen = containerType.length

  return [
    container,
    containerType,
    {
      render(tokens: Token[], idx: number): string {
        const token = tokens[idx]
        if (!token) {
          return ''
        }

        // Get the title from token info or use defaultTitle
        const rawTitle = token.info.trim().slice(containerTypeLen).trim() || defaultTitle

        // Process the title as inline markdown
        const titleHtml = md ? md.renderInline(rawTitle) : rawTitle

        if (containerType === 'details') {
          return token.nesting === 1
            ? `<details class="markdown-note markdown-note--${containerType}"><summary class="markdown-note__title">${titleHtml}</summary>\n`
            : '</details>\n'
        }

        return token.nesting === 1
          ? `<div class="markdown-note markdown-note--${containerType}"><p class="markdown-note__title">${titleHtml}</p>\n`
          : '</div>\n'
      },
    },
  ]
}

md.use(containersPlugin, containers, createContainer)

const markdownContent = `
::: tip
This is a tip.
:::

::: warning
This is a warning!
:::
`

const renderedOutput = md.render(markdownContent)

console.log('Rendered Output:', renderedOutput)

Example Output

The rendered output will look like this:

<div class="markdown-note markdown-note--tip">
  <p class="markdown-note__title">TIP</p>
  <p>This is a tip container.</p>
</div>

<div class="markdown-note markdown-note--warning">
  <p class="markdown-note__title">WARNING</p>
  <p>This is a warning container.</p>
</div>

Options

The md-plugin-containers plugin supports the following options:

| Option | Type | Default | Description | | ------------ | --------------------------------------------- | ------- | ------------------------------------------------------- | | containers | Array<{ type: string; defaultTitle: string }> | [] | List of containers with their types and default titles. | | render | Function | null | Custom rendering function for containers. | | defaultTitle | string | null | Default title for containers. | | md | MarkdownIt | null | Markdown-It instance for rendering. |

Defining Custom Containers

You can define custom containers with their own styles or components:

function createContainer(container, containerType, defaultTitle, md) {
  const containerTypeLen = containerType.length

  return [
    container,
    containerType,
    {
      render(tokens, idx) {
        const token = tokens[idx]
        const rawTitle = token.info.trim().slice(containerTypeLen).trim() || defaultTitle

        // Process the title as inline markdown
        const titleHtml = md ? md.renderInline(rawTitle) : rawTitle

        if (containerType === 'details') {
          return token.nesting === 1
            ? `<details class="markdown-note markdown-note--${containerType}"><summary class="markdown-note__title">${titleHtml}</summary>\n`
            : '</details>\n'
        }

        return token.nesting === 1
          ? `<div class="markdown-note markdown-note--${containerType}"><p class="markdown-note__title">${titleHtml}</p>\n`
          : '</div>\n'
      },
    },
  ]
}

Adding Titles

Containers can include titles by default or allow custom titles to be specified:

::: note Custom Note Title
This is a custom note with a title.
:::

Rendered Output:

<div class="note">
  <strong>Custom Note Title</strong>
  <p>This is a custom note with a title.</p>
</div>

Nested Containers

Containers can be nested if your rendering logic supports it:

::: note Outer Note
::: warning Inner Warning
Be cautious!
::::::

Rendered Output:

<div class="note">
  <p>Outer Note</p>
  <div class="warning">
    <p>Be cautious!</p>
  </div>
</div>

Testing

To run the tests for this plugin, use the following command:

pnpm test

Documentation

In case this README falls out of date, please refer to the documentation for the latest information.

Support

If md-plugin-containers is useful in your workflow and you want to support ongoing maintenance:

• GitHub Sponsors: https://github.com/sponsors/hawkeye64
• PayPal: https://paypal.me/hawkeye64

License

This plugin is licensed under the MIT License. See the LICENSE file for details.