Контейнеры

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

Подключение и базовая настройка

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

npm install markdown-it markdown-it-container

После установки подключение выглядит следующим образом:

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

const md = new MarkdownIt();

md.use(container, 'warning'); // создаём контейнер типа "warning"

Здесь 'warning' — это имя контейнера. Оно используется для идентификации блоков и последующего применения CSS или других стилей.

Синтаксис контейнеров

Контейнеры оформляются с использованием трёх двоеточий ::::

:::warning
Внимание! Этот блок содержит важную информацию.
:::

При рендеринге в HTML получится блок:

<div class="warning">
  <p>Внимание! Этот блок содержит важную информацию.</p>
</div>

Ключевые моменты синтаксиса:

  • Начало контейнера: :::{имя_контейнера}
  • Конец контейнера: :::
  • Содержимое может быть любым Markdown-кодом (списки, заголовки, ссылки).

Создание пользовательских контейнеров с обработкой содержимого

Плагин позволяет определить собственные функции рендеринга:

md.use(container, 'note', {
  render: function (tokens, idx) {
    const token = tokens[idx];
    if (token.nesting === 1) {
      return '<div class="note">\n';
    } else {
      return '</div>\n';
    }
  }
});

Пояснение:

  • tokens[idx].nesting === 1 — открывающий тег.
  • tokens[idx].nesting === -1 — закрывающий тег.
  • Функция возвращает HTML-код для контейнера.

Такой подход даёт полный контроль над разметкой и стилями блока.

Контейнеры с параметрами

Можно передавать параметры в контейнер, чтобы динамически добавлять классы или атрибуты:

:::note important
Это важная заметка.
:::

При настройке плагина:

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) {
      const classes = m[1] ? `note ${m[1]}` : 'note';
      return `<div class="${classes}">\n`;
    } else {
      return '</div>\n';
    }
  }
});

Результат HTML:

<div class="note important">
  <p>Это важная заметка.</p>
</div>

Преимущества такого подхода:

  • Поддержка нескольких вариантов оформления одного типа контейнера.
  • Возможность добавлять CSS-классы через Markdown.
  • Простая интеграция с внешними стилями.

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

Markdown-it поддерживает вложенность контейнеров:

:::warning
Внутренний текст.
:::note
Дополнительная информация.
:::
Текст после внутреннего контейнера.
:::

При рендеринге получается:

<div class="warning">
  <p>Внутренний текст.</p>
  <div class="note">
    <p>Дополнительная информация.</p>
  </div>
  <p>Текст после внутреннего контейнера.</p>
</div>

Особенности вложенных контейнеров:

  • Контейнеры могут содержать любые другие блоки Markdown, включая списки и заголовки.
  • Необходимо корректно управлять nesting в функции render.

Практическое применение

Контейнеры позволяют создавать:

  • Предупреждения и ошибки (warning, error)
  • Заметки и подсказки (note, tip)
  • Секционные блоки документации (разделы с примерами кода, инструкциями)
  • Структурированные блоки с атрибутами для динамического оформления

Пример интеграции с CSS:

.warning {
  background-color: #fff3cd;
  border-left: 5px solid #ffc107;
  padding: 10px;
  margin: 10px 0;
}

.note {
  background-color: #e7f3fe;
  border-left: 5px solid #2196F3;
  padding: 10px;
  margin: 10px 0;
}

Markdown-код автоматически преобразуется в стилизованные блоки без дополнительного HTML-кода в исходном тексте.

Взаимодействие с другими плагинами

Контейнеры могут комбинироваться с другими расширениями Markdown-it:

  • markdown-it-attrs — добавление атрибутов к контейнерам
  • markdown-it-footnote — сноски внутри контейнеров
  • markdown-it-highlightjs — подсветка кода внутри контейнеров

Это расширяет возможности создания сложной документации и технических статей с красивым форматированием.

Советы по организации контейнеров

  • Использовать чётко определённые имена для каждого типа контейнера.
  • Разделять стили CSS по назначению (предупреждения, заметки, примеры).
  • Поддерживать вложенность, но избегать слишком глубокой, чтобы не ухудшить читаемость.
  • Использовать validate для фильтрации допустимых параметров контейнера и предотвращения ошибок.

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

Оглавление