Типы токенов

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

Основные свойства токена

У любого токена есть несколько ключевых свойств:

• type — тип токена, определяющий семантику элемента (paragraph_open, inline, heading_open, fence и т.д.).

• tag — HTML-тег, который будет сгенерирован (p, h1, ul, code и т.п.).

• attrs — массив атрибутов в формате [ключ, значение], которые будут применены к тегу.

• map — массив из двух чисел [startLine, endLine], указывающий диапазон строк исходного документа.

• nesting — показатель уровня вложенности:

  • 1 — открывающий токен (например, начало параграфа <p>),
  • 0 — одиночный токен (например, инлайн-элемент <img>),
  • -1 — закрывающий токен (например, конец параграфа </p>).

• level — числовое значение глубины вложенности, которое помогает при построении дерева токенов.

• children — массив вложенных токенов (только для токенов с типом inline).

Классификация токенов

Markdown-it выделяет несколько категорий токенов в зависимости от их назначения:

1. Блочные токены (Block tokens) Блочные токены формируют структуру документа на уровне блоков. К ним относятся:

   • paragraph_open / paragraph_close — параграфы.
   • heading_open / heading_close — заголовки всех уровней.
   • blockquote_open / blockquote_close — цитаты.
   • list_item_open / list_item_close — элементы списков.
   • bullet_list_open / bullet_list_close и ordered_list_open / ordered_list_close — списки.
   • fence — многострочный код.
   • hr — горизонтальная линия.

2. Инлайн-токены (Inline tokens) Эти токены находятся внутри блочных элементов и описывают текст и его форматирование:

   • text — простой текст.
   • code_inline — инлайн-код.
   • em_open / em_close — выделение курсивом.
   • strong_open / strong_close — выделение жирным.
   • link_open / link_close — ссылки.
   • image — вставка изображений.
   • softbreak / hardbreak — переносы строк.

3. Специальные токены Используются для управления парсингом и рендерингом:

   • inline — контейнер для вложенных токенов.
   • html_block / html_inline — сырой HTML.
   • footnote_reference / footnote_block_open — сноски.
   • math_block / math_inline — математические выражения (если подключены соответствующие плагины).

Примеры создания токенов

Markdown-it позволяет создавать токены программно с помощью конструктора Token:

const Token = require('markdown-it/lib/token');

const paragraphOpen = new Token('paragraph_open', 'p', 1);
paragraphOpen.attrs = [['class', 'text-block']];
paragraphOpen.map = [0, 1];

const text = new Token('text', '', 0);
text.content = 'Пример текста внутри параграфа.';

const paragraphClose = new Token('paragraph_close', 'p', -1);

const tokens = [paragraphOpen, text, paragraphClose];

В этом примере создаётся параграф с классом text-block и текстом внутри. Последовательность токенов полностью соответствует структуре HTML: открывающий тег, содержимое, закрывающий тег.

Взаимосвязь токенов и дерева документа

Каждый токен имеет свой уровень вложенности (level) и связь с родительскими или дочерними элементами через массив children. Для блочных элементов children обычно пустой, а для инлайн-токенов — содержит токены текста и форматирования. Это позволяет строить дерево документа и облегчает рендеринг в HTML или другие форматы.

Практическое использование

Токены широко применяются для:

• Настройки рендеринга отдельных элементов. Например, добавление пользовательских классов к заголовкам или параграфам.
• Плагинов, изменяющих содержимое Markdown на лету (например, преобразование эмодзи или специальных ссылок).
• Разбора документа для анализа или генерации оглавления.
• Контроля безопасности при работе с HTML внутри Markdown (через фильтрацию токенов).

Итоговая структура токена

Краткая схема ключевых свойств токена:

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