@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 npm:
npm install @md-plugins/md-plugin-containers
# Or with Yarn:
yarn add @md-plugins/md-plugin-containers
# Or with pnpm:
pnpm add @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'

const md = new MarkdownIt()

const containers = [
  { type: 'warning', defaultTitle: 'Warning' },
  { type: 'tip', defaultTitle: 'Tip' },
  { type: 'details', defaultTitle: 'Details' },
]

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

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

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

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

md.use(containersPlugin, containers, createContainer)

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

:::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="note">
  <p>This is a note.</p>
</div>

<div class="warning">
  <p>This is a warning!</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. |

Defining Custom Containers

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

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

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

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

        return token.nesting === 1
          ? `<div class="markdown-note markdown-note--${containerType}"><p class="markdown-note__title">${title}</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.

License

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