Плагин для контейнеров

Markdown-it поддерживает расширяемую систему плагинов, одним из которых является плагин для контейнеров. Контейнеры позволяют создавать специальные блоки с настраиваемым содержимым и стилями, которые невозможно реализовать с помощью стандартного синтаксиса Markdown. Это полезно для выделения информации, создания предупреждений, заметок, примеров кода или других визуально оформленных блоков.

Установка и подключение плагина

Для работы с контейнерами используется официальный плагин markdown-it-container. Его установка производится через npm:

npm install markdown-it-container

Подключение к Markdown-it осуществляется следующим образом:

const MarkdownIt = require('markdown-it');
const container = require('markdown-it-container');

const md = new MarkdownIt();
md.use(container, 'info');

Здесь 'info' — это название контейнера. В дальнейшем его можно использовать в Markdown-файле следующим образом:

::: info
Это информационный блок
:::

Базовая структура контейнера

Контейнеры имеют три основные компоненты:

  1. Начальная строка — определяется как ::: плюс название контейнера и необязательные параметры.
  2. Содержимое блока — обычный Markdown, который будет обработан внутри контейнера.
  3. Закрывающая строка — строка с тремя двоеточиями :::.

Пример:

::: warning
Внимание! Этот блок предназначен для предупреждений.
:::

На этапе рендеринга этот блок будет преобразован в HTML:

<div class="warning">
  <p>Внимание! Этот блок предназначен для предупреждений.</p>
</div>

Настройка внешнего вида контейнеров

Контейнеры используют CSS-классы, соответствующие названию контейнера. Это позволяет настраивать визуальное оформление через стили. Пример CSS:

.info {
    background-color: #e0f7fa;
    border-left: 4px solid #00acc1;
    padding: 10px;
}

.warning {
    background-color: #fff3e0;
    border-left: 4px solid #ff9800;
    padding: 10px;
}

Создание кастомных контейнеров с проверкой условий

Плагин markdown-it-container позволяет добавлять кастомную логику при открытии и закрытии блока. Для этого используется объект с функциями validate и render:

md.use(container, 'note', {
  validate: function(params) {
    return params.trim().match(/^note\s+(.*)$/);
  },
  render: function(tokens, idx) {
    const m = tokens[idx].info.trim().match(/^note\s+(.*)$/);
    if (tokens[idx].nesting === 1) {
      // Открывающий тег
      return `<div class="note"><strong>${md.utils.escapeHtml(m[1])}</strong>\n`;
    } else {
      // Закрывающий тег
      return '</div>\n';
    }
  }
});

Markdown для этого блока может выглядеть так:

::: note Важная заметка
Содержимое заметки.
:::

Результат рендеринга:

<div class="note"><strong>Важная заметка</strong>
<p>Содержимое заметки.</p>
</div>

Вложенные контейнеры

Markdown-it поддерживает вложенные контейнеры, если использовать разные имена для блоков:

::: warning
Внимание!
::: info
Дополнительная информация
:::
:::

При рендеринге получится два вложенных блока:

<div class="warning">
  <p>Внимание!</p>
  <div class="info">
    <p>Дополнительная информация</p>
  </div>
</div>

Вложенные блоки позволяют создавать сложные структуры, например, предупреждения с дополнительными подсказками.

Использование параметров контейнера

Параметры после названия контейнера можно использовать для передачи данных в рендер-функцию. Это удобно для динамического формирования заголовков, идентификаторов или других атрибутов HTML:

md.use(container, 'example', {
  validate: function(params) {
    return params.trim().match(/^example\s+(.*)$/);
  },
  render: function(tokens, idx) {
    const m = tokens[idx].info.trim().match(/^example\s+(.*)$/);
    if (tokens[idx].nesting === 1) {
      return `<div class="example" data-title="${md.utils.escapeHtml(m[1])}">\n`;
    } else {
      return '</div>\n';
    }
  }
});

Markdown:

::: example Заголовок блока
Содержимое блока.
:::

HTML:

<div class="example" data-title="Заголовок блока">
  <p>Содержимое блока.</p>
</div>

Практические советы

  • Стилизация через CSS — основное средство управления внешним видом блоков. Контейнеры добавляют только HTML-структуру и CSS-классы.
  • Использование нескольких типов контейнеров — рекомендуется присваивать каждому типу уникальное название для предотвращения конфликтов.
  • Валидация входных параметров — позволяет контролировать, какие блоки будут рендериться, и создавать динамические заголовки.
  • Поддержка вложенности — Markdown-it корректно обрабатывает вложенные контейнеры, что делает его удобным для создания комплексных блоков документации.

Контейнеры в Markdown-it предоставляют мощный инструмент для расширения стандартного синтаксиса Markdown, позволяя создавать структурированные и стилизованные блоки с произвольным содержимым и динамическими параметрами.

Оглавление