Типы токенов

Библиотека Marked — это мощный парсер Markdown в JavaScript, который преобразует текст в HTML. Основой её работы является разбор текста на токены, каждый из которых соответствует отдельной конструкции Markdown. Понимание типов токенов позволяет контролировать обработку контента, настраивать рендеринг и создавать собственные расширения.

1. Базовое понятие токена

Токен — это объект, который описывает отдельный элемент Markdown с его типом, содержимым и дополнительными свойствами. Каждый токен создаётся на этапе лексического анализа, когда Marked читает исходный текст и разделяет его на логические блоки.

Структура типичного токена:

{
  type: "paragraph",    // Тип токена
  raw: "Текст параграфа\n", // Исходный текст
  text: "Текст параграфа"   // Обработанный текст
}
  • type — ключевое поле, определяющее тип токена.
  • raw — полное содержимое исходного текста, включающее возможные символы Markdown.
  • text — очищенное или нормализованное содержимое, которое будет использоваться рендерером.

2. Основные типы токенов

2.1. Блочные токены (Block Tokens)

Блочные токены описывают элементы, которые занимают целую строку или несколько строк текста. Они включают:

  • heading — заголовки (#, ## и т. д.).

    Свойства:

    • depth — уровень заголовка (от 1 до 6).
    • text — содержимое заголовка без символов #.

  • paragraph — параграфы.

    Свойства:

    • text — текст параграфа без Markdown-разметки.
    • tokens — массив вложенных inline-токенов.

  • list — списки (маркированные или нумерованные).

    Свойства:

    • ordered — булево значение, указывающее на тип списка.
    • start — начальный номер для нумерованного списка.
    • items — массив токенов для элементов списка.

  • blockquote — блоки цитирования.

    Свойства:

    • tokens — массив вложенных токенов, представляющих содержимое цитаты.

  • code — блоки кода.

    Свойства:

    • text — текст кода.
    • lang — язык программирования, если указан.

  • hr — горизонтальная линия.

    Свойства минимальны, обычно raw и type.

2.2. Внутренние токены (Inline Tokens)

Inline-токены находятся внутри блочных элементов, таких как параграфы, заголовки или элементы списка. Основные inline-токены:

  • text — простой текст без форматирования.

  • strong — жирное начертание (**текст** или __текст__).

    • text — содержимое жирного текста.
    • tokens — массив вложенных inline-токенов.

  • em — курсивное начертание (*текст* или _текст_).

  • codespan — встроенный код (обрамлённый обратными апострофами).

    • text — содержимое кода.

  • link — гиперссылки.

    • href — адрес ссылки.
    • title — необязательный атрибут title.
    • text — отображаемый текст ссылки.

  • image — изображения.

    • href — путь к изображению.
    • title — текст подсказки.
    • text — альтернативный текст (alt).

3. Вложенность токенов

Каждый блочный токен может содержать массив inline-токенов. Например, параграф может иметь жирный текст, ссылки и встроенный код. Структура вложенности выглядит так:

{
  type: "paragraph",
  text: "Ссылка и жирный текст",
  tokens: [
    { type: "link", href: "https://example.com", text: "Ссылка" },
    { type: "text", text: " и " },
    { type: "strong", text: "жирный текст" }
  ]
}

Это позволяет рендереру Marked точно воспроизводить форматирование Markdown, сохраняя структуру документа.

4. Специальные токены

Некоторые токены не имеют прямого визуального аналога, но играют ключевую роль:

  • space — пустая строка, которая разделяет блочные элементы.

  • html — встроенный HTML-код, который парсер пропускает без изменения.

  • table — таблицы, содержащие:

    • header — массив ячеек заголовка.
    • align — выравнивание колонок (left, center, right).
    • rows — массив массивов ячеек с текстом.

5. Создание и обработка токенов вручную

Marked позволяет создавать токены вручную для расширенной функциональности:

const tokens = [
  { type: "heading", depth: 2, text: "Пример заголовка" },
  { type: "paragraph", text: "Текст параграфа" }
];
const renderer = new marked.Renderer();
tokens.forEach(token => {
  console.log(renderer[token.type](token));
});

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

6. Итоговая схема типов токенов

Категория Типы токенов
Блочные heading, paragraph, list, blockquote, code, hr, table
Внутренние text, strong, em, codespan, link, image
Специальные space, html

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

Оглавление