Совместимость с CommonMark

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

Основные принципы совместимости

CommonMark задаёт строгие правила, как должны обрабатываться заголовки, списки, блоки кода, ссылки, цитаты и другие элементы Markdown. Markdown-it реализует эти правила максимально полно, что позволяет:

  • Обеспечивать предсказуемый результат парсинга на любых платформах.
  • Совместимо обрабатывать файлы Markdown, созданные с использованием других CommonMark-совместимых инструментов.
  • Использовать строгую структуру AST (abstract syntax tree), которая соответствует CommonMark.

Заголовки и их обработка

Markdown-it поддерживает оба типа заголовков:

  1. ATX-заголовки: #, ##, ### и так далее.

    • Количество решёток соответствует уровню заголовка.
    • Пробел после символов решётки обязателен для строгого соблюдения CommonMark.
    • Лишние пробелы в конце строки игнорируются, что соответствует спецификации.

  2. Setext-заголовки:

    Заголовок уровня 1
=================
Заголовок уровня 2
-----------------
    • Markdown-it корректно различает уровни по символам = и -.
    • Обрабатываются только как заголовки при соблюдении синтаксиса CommonMark.

Списки и вложенность

Списки поддерживаются как маркированные (-, *, +), так и нумерованные (1., 2. и т. д.). Важные нюансы:

  • Вложенные списки должны иметь отступ не менее 2 пробелов от родительского элемента.
  • Markdown-it строго соблюдает правила CommonMark по определению, является ли элемент частью списка или обычным параграфом.
  • Пустые строки внутри списков корректно интерпретируются для разделения элементов.

Пример корректного вложенного списка:

- Пункт 1
  - Вложенный пункт 1.1
  - Вложенный пункт 1.2
- Пункт 2

Кодовые блоки и inline-код

Markdown-it поддерживает два формата кода:

  1. Inline-код: обрамляется обратными апострофами `код`.

    • Лишние пробелы внутри апострофов сохраняются в точности.
    • Поддерживаются несколько последовательных апострофов для вложенных случаев.

  2. Fenced-код: блоки с тройными апострофами или тильдами:

    ```javascript
console.log("Hello, World!");
```
    • Возможность указать язык для подсветки синтаксиса.
    • Markdown-it учитывает спецификацию CommonMark, позволяя экранировать символы внутри блока.

Ссылки и изображения

Markdown-it обрабатывает inline-ссылки, reference-ссылки и изображения в строгом соответствии с CommonMark:

  • Inline-ссылка: [текст](url "title")

    • Поддерживается необязательный заголовок (title).
    • Вложенные скобки и пробелы корректно интерпретируются.

  • Reference-ссылка:

    [текст][id]
...
[id]: http://example.com "Example"
    • Markdown-it связывает ссылки с их идентификаторами независимо от их положения в документе.
    • Допустимо определять идентификаторы в любом регистре.

Блоки цитат

Блоки цитат создаются с использованием символа >:

> Это блок цитаты
> с несколькими строками.
  • Markdown-it поддерживает вложенные цитаты: >> создаёт цитату внутри цитаты.
  • Обрабатываются переносы строк и пустые строки в соответствии с CommonMark.

Особенности совместимости

  • Markdown-it полностью соблюдает спецификацию CommonMark v0.29.
  • Парсер корректно обрабатывает крайние случаи: незакрытые теги, неправильные отступы, экранированные символы.
  • Встроенные правила можно расширять с помощью плагинов без нарушения совместимости, что делает библиотеку гибкой для любых проектов.

Проверка соответствия

Markdown-it предоставляет встроенный тестовый режим для проверки совместимости с CommonMark:

const md = require('markdown-it')();
console.log(md.render('# Заголовок\n\nПараграф текста'));
  • Этот код гарантирует, что вывод соответствует спецификации CommonMark.
  • Использование стандартных тестов CommonMark позволяет убедиться, что обработка Markdown точна и предсказуема.

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

Оглавление