Понятие токенов

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

Структура токена

Каждый токен — это объект с набором свойств, определяющих его тип и поведение. Основные свойства:

  • type — строка, обозначающая тип токена, например, paragraph_open, inline, heading_open, text.
  • tag — HTML-тег, соответствующий токену (p, h1, ul и т. д.).
  • attrs — массив атрибутов [имя, значение] для HTML-тега.
  • map — массив из двух чисел [начальная строка, конечная строка] исходного документа, полезный для подсветки синтаксиса.
  • nesting — целое число, определяющее открытие/закрытие блока: 1 — открытие, -1 — закрытие, 0 — самозакрывающийся токен.
  • level — глубина вложенности токена, начинается с 0.
  • children — массив вложенных токенов (используется для токенов типа inline).
  • content — текстовое содержимое, актуальное для текстовых токенов (text, code_inline).
  • markup — исходный Markdown-синтаксис, например * или **.
  • info — дополнительная информация для специализированных токенов, например, язык блока кода в fence.
  • meta — объект, хранящий произвольные метаданные, которые могут быть добавлены через плагины.

Пример токена для абзаца с текстом:

{
  type: 'paragraph_open',
  tag: 'p',
  attrs: null,
  map: [0, 1],
  nesting: 1,
  level: 0,
  children: null,
  content: '',
  markup: '',
  info: '',
  meta: null
}

Типы токенов

Токены делятся на блоковые и строчные (inline):

  1. Блоковые токены представляют крупные структуры:

    • paragraph_open / paragraph_close — открытие и закрытие абзаца.
    • heading_open / heading_close — заголовки.
    • bullet_list_open / bullet_list_close — маркированные списки.
    • ordered_list_open / ordered_list_close — нумерованные списки.
    • blockquote_open / blockquote_close — блоки цитирования.
    • fence — блоки кода с возможностью указания языка.

  2. Строчные токены (inline) содержатся внутри блоковых:

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

Блоковые токены формируют структуру документа, а inline-токены — содержимое блоков.

Вложенность и уровни

Свойство level помогает определять иерархию элементов. Например:

  • level = 0 — первый уровень документа.
  • level = 1 — токены внутри первого блока, например, текст внутри абзаца.
  • level = 2 — вложенные элементы, например, выделенный текст внутри параграфа.

nesting совместно с level позволяет корректно строить дерево токенов, которое затем используется рендерером для генерации HTML.

Работа с токенами

После парсинга Markdown создается массив токенов. Каждый элемент массива представляет либо начало блока (*_open), либо конец (*_close), либо содержимое (text или inline). Пример обработки:

const md = require('markdown-it')();
const tokens = md.parse('**Пример текста**', {});

tokens.forEach(token => {
  console.log(token.type, token.tag, token.content);
});

Результат покажет последовательность токенов:

  1. strong_open — открытие жирного текста.
  2. text — содержимое “Пример текста”.
  3. strong_close — закрытие жирного текста.

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

Плагины могут добавлять данные в meta, модифицировать attrs или создавать новые токены. Это позволяет расширять стандартный синтаксис Markdown, например, добавлять подсветку синтаксиса в блоках кода, дополнительные атрибуты к ссылкам, кастомные таблицы и блоки уведомлений.

Визуализация токенов

Для сложных документов полезно визуализировать токены в виде дерева:

paragraph_open (level 0)
  inline (level 1)
    strong_open (level 2)
    text "Пример текста" (level 2)
    strong_close (level 2)
paragraph_close (level 0)

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

Итоговое понимание

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

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

Оглавление