Объект Token

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

Структура объекта Token

Объект Token обладает рядом ключевых свойств, определяющих его поведение и внешний вид при рендеринге:

  • type Строка, указывающая тип токена. Типы токенов делятся на блоковые и строчные. Примеры: paragraph_open, paragraph_close, inline, heading_open, heading_close, fence.

  • tag HTML-тег, соответствующий токену. Для токена типа paragraph_open это будет p, для heading_open — h1, h2 и так далее. Если токен не соответствует конкретному HTML-тегу, свойство может быть пустым.

  • attrs Массив массивов [имя, значение], представляющий HTML-атрибуты тега. Например: [["class", "highlight"]]. Если атрибутов нет, свойство равно null.

  • map Массив из двух чисел [начальная_строка, конечная_строка], указывающий диапазон строк исходного Markdown-документа, к которому относится токен. Применяется для точного отображения местоположения элементов при обработке или подсветке синтаксиса.

  • nesting Целое число, обозначающее уровень вложенности токена:

    • 1 — открывающий тег,
    • 0 — самостоятельный или inline-токен,
    • -1 — закрывающий тег.

  • level Число, показывающее уровень вложенности токена относительно документа. Используется для управления структурой документа при рендеринге.

  • children Массив токенов, вложенных в данный токен. Присутствует для блоков типа inline, где содержимое параграфа или заголовка разбивается на отдельные токены для форматирования (например, текст, ссылки, эмфазы).

  • content Строка с исходным текстом токена. Применяется для токенов без вложенных элементов, таких как текст или код.

  • markup Строка с символами Markdown, которые создают данный элемент (например, * для выделения или ``` для кода). Используется для точного рендеринга и анализа исходного документа.

  • info Строка с дополнительной информацией о токене, чаще всего используется в токенах fence для указания языка программирования.

  • meta Произвольный объект для хранения данных, специфичных для плагинов или пользовательских обработчиков.

Примеры создания и использования Token

Создание токена вручную позволяет гибко управлять процессом рендеринга. Пример генерации токена параграфа с текстом:

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

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

const inlineToken = new Token('inline', '', 0);
inlineToken.content = 'Пример текста параграфа';
inlineToken.children = [];

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

const tokens = [paragraphOpen, inlineToken, paragraphClose];

В данном примере создается блок параграфа с классом text-center, содержащий простой текст.

Работа с вложенными токенами

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

const textToken = new Token('text', '', 0);
textToken.content = 'выделенный текст';

const emOpen = new Token('em_open', 'em', 1);
const emClose = new Token('em_close', 'em', -1);

emOpen.children = [textToken];

Связь Token с рендерером

Рендеринг документа в HTML выполняется через функцию md.renderer.render(tokens, options, env), где tokens — массив объектов Token. Рендерер проходит по каждому токену, используя его свойства (type, tag, attrs, content) для генерации финального HTML.

Использование map для синхронизации с исходным текстом

Свойство map критично для приложений, где требуется подсветка или анализ исходного Markdown. Например, редакторы кода могут отображать, какие строки относятся к конкретному элементу:

inlineToken.map = [2, 3]; // токен относится к строкам 2 и 3 исходного файла

Метаданные и расширения

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

Объект Token в Markdown-it представляет собой универсальный механизм для внутреннего представления документа. Глубокое понимание его структуры и возможностей позволяет создавать мощные плагины, управлять точным рендерингом и эффективно обрабатывать Markdown-документы в любых приложениях на JavaScript.

Оглавление