Экранирование HTML

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

Встроенная поддержка HTML

Markdown-it по умолчанию поддерживает HTML-теги в тексте. Например:

<div>Пример блока HTML</div>

При рендеринге в HTML это будет преобразовано в настоящий <div> элемент. Для случаев, когда необходимо вывести тег как текст, используется экранирование.

Экранирование HTML

Экранирование позволяет преобразовать специальные символы в их HTML-сущности:

  • < → &lt;
  • > → &gt;
  • & → &amp;
  • " → &quot;
  • ' → &#39;

Markdown-it предлагает гибкость в обработке HTML через опции конфигурации и плагины. Основная опция, влияющая на экранирование, — html.

const md = require('markdown-it')({
  html: false  // Отключение встроенного HTML
});

Установка html: false гарантирует, что любой HTML в тексте будет автоматически экранироваться, а не рендериться как разметка.

Использование inline-кода для экранирования

Markdown поддерживает обрамление текста обратными апострофами (`) для отображения как кода:

`<div>Текст</div>`

Markdown-it преобразует это в:

<code>&lt;div&gt;Текст&lt;/div&gt;</code>

Такой подход полезен для документации и демонстрации HTML-кода, не нарушая структуру документа.

Плагины для расширенного экранирования

Markdown-it поддерживает плагины, которые позволяют тонко настраивать обработку HTML. Один из популярных — markdown-it-attrs, который позволяет добавлять атрибуты к элементам, сохраняя при этом возможность экранирования.

Пример использования:

const md = require('markdown-it')()
  .use(require('markdown-it-attrs'));

const result = md.render(`
<div{.custom-class}>Пример</div>
`);

Если включить html: false, содержимое тега будет экранировано:

&lt;div class="custom-class"&gt;Пример&lt;/div&gt;

Экранирование через фильтры

Для более сложных случаев можно использовать регистрируемые рендер-функции (renderer.rules) в Markdown-it. Например, чтобы экранировать все HTML-теги кроме определённых:

const md = require('markdown-it')();

const defaultRender = md.renderer.rules.html_block || function(tokens, idx, options, env, self) {
  return self.renderToken(tokens, idx, options);
};

md.renderer.rules.html_block = function(tokens, idx, options, env, self) {
  const content = tokens[idx].content;
  // Экранируем все угловые скобки
  const escaped = content.replace(/</g, '&lt;').replace(/>/g, '&gt;');
  return escaped;
};

Такой подход даёт полную свободу в контроле над тем, какие HTML-теги разрешены к рендерингу, а какие должны быть преобразованы в текст.

Практическая рекомендация

  • Для безопасного рендеринга пользовательского ввода всегда устанавливать html: false.
  • Для документации или демонстрации кода использовать inline-код или блоки кода (```) для автоматического экранирования.
  • Для специфических требований — использовать кастомные рендер-правила или плагины.

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

Оглавление