Параметр mangle

Параметр mangle в библиотеке Marked предназначен для управления способностью библиотеки автоматически шифровать или маскировать адреса электронной почты в тексте Markdown. Основная цель этой функции — защита email-адресов от спам-ботов, при этом визуально и функционально для пользователя адрес остаётся доступным и читаемым.

Принцип работы

Когда включён mangle, библиотека преобразует символы в адресе электронной почты в HTML-сущности. Например, символ @ будет заменён на @, а точка — на .. В результате код страницы остаётся безопасным для индексации и трудночитаемым для автоматических сканеров, но браузер корректно отображает адрес и позволяет пользователю кликать по ссылке.

Тип значения

Параметр mangle может принимать следующие значения:

  • true — включение автоматического шифрования email-адресов. По умолчанию Marked использует это поведение.
  • false — отключение маскировки адресов. Email-адреса остаются в исходной форме в HTML.

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

import { marked } from 'marked';

const markdown = 'Напишите мне на ';

const htmlWithMangle = marked(markdown, { mangle: true });
const htmlWithoutMangle = marked(markdown, { mangle: false });

console.log(htmlWithMangle); 
// Выведет: Напишите мне на email@example.com

console.log(htmlWithoutMangle); 
// Выведет: Напишите мне на email@example.com

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

mangle тесно связан с параметром headerIds и опцией xhtml:

  • headerIds отвечает за генерацию идентификаторов заголовков. Если идентификаторы сгенерированы автоматически и содержат символы @ или ., их обработка может пересекаться с функцией mangle. При использовании mangle: true такие символы внутри ссылок email также будут преобразованы в HTML-сущности.
  • xhtml управляет закрытием одиночных тегов. При включённом mangle и xhtml: true генерация для email-адресов остаётся корректной, соблюдая синтаксис XHTML.

Особенности и ограничения

  1. Только email-адреса Параметр mangle применяет преобразование исключительно к адресам в формате local@domain. Обычные тексты или ссылки на сайты не подвергаются маскировке.

  2. Влияние на SEO Так как текст остаётся читаемым для браузера, но преобразован в HTML-сущности, индексация адресов поисковыми системами может быть частично затруднена. Это не критично, так как email-адреса редко должны индексироваться.

  3. Комбинация с пользовательскими рендерерами При использовании собственного рендерера через marked.use({ renderer: customRenderer }), важно учитывать, что функция mangle вызывается до передачи данных в рендерер. Если требуется собственная обработка email, mangle может быть отключён, а шифрование реализовано вручную.

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

  • В проектах с открытым доступом к исходному коду страниц, где адреса email нужно защитить от спам-ботов, рекомендуется использовать mangle: true.
  • В закрытых системах или внутренних документациях, где безопасность email не критична, можно использовать mangle: false для упрощения обработки HTML и снижения количества сущностей.
  • Для совместимости с Markdown, который может содержать нестандартные формы адресов (user+tag@example.com), проверять корректность генерации ссылок при включённом mangle.

Внутренняя реализация

Marked использует функцию escapeEmail для преобразования символов email в HTML-сущности. Алгоритм следующий:

  1. Разбивка email на отдельные символы.

  2. Для каждого символа случайным образом выбирается одна из форм:

    • Десятичная HTML-сущность (&#код;)
    • Шестнадцатеричная HTML-сущность (&#xкод;)
    • Сам символ без изменений (редко, для разнообразия)

  3. Сборка строки и подстановка в href тега .

Такой подход делает адрес менее предсказуемым для спам-ботов, сохраняя полную работоспособность.

Оглавление