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

Markdown-it предоставляет возможность работы с расширенной спецификацией Markdown, совместимой с GitHub Flavored Markdown (GFM). GFM — это расширение стандартного Markdown, включающее такие возможности, как таблицы, задачи в списках, автоматические ссылки, подчёркивания, выравнивание и многое другое. Поддержка GFM в Markdown-it реализуется через опции и плагины, позволяя гибко настраивать парсер под специфические требования.

Включение GFM

Для активации совместимости с GFM используется объект настроек при создании экземпляра Markdown-it. Основные опции, влияющие на GFM:

const MarkdownIt = require('markdown-it');
const md = new MarkdownIt({
  html: true,        // Разрешает HTML-теги в тексте
  linkify: true,     // Автоматическая конвертация URL в ссылки
  typographer: true, // Применение типографских замен
});

Опция linkify позволяет автоматически распознавать URL и email-адреса, что является частью GFM. Для полного включения GFM также рекомендуется использовать дополнительные плагины, например markdown-it-task-lists и markdown-it-footnote.

Таблицы

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

const md = new MarkdownIt()
  .use(require('markdown-it-table'));

Синтаксис таблиц в GFM:

| Заголовок 1 | Заголовок 2 |
|------------|------------|
| Ячейка 1  | Ячейка 2  |
| Ячейка 3  | Ячейка 4  |

Особенности:

  • Строка с --- обязательно отделяет заголовок от содержимого.
  • Выравнивание текста задаётся с помощью двоеточий: :--- (влево), :---: (по центру), ---: (вправо).
  • Пустые ячейки поддерживаются.

Markdown-it корректно обрабатывает такие таблицы, превращая их в HTML-элементы <table>, <thead>, <tbody>, <tr>, <td> и <th>.

Задачи в списках

GFM позволяет создавать интерактивные чекбоксы в списках:

- [ ] Задача не выполнена
- [x] Задача выполнена

Для Markdown-it требуется подключение плагина markdown-it-task-lists:

const md = new MarkdownIt()
  .use(require('markdown-it-task-lists'), { enabled: true });

Особенности:

  • - [ ] создаёт пустой чекбокс.
  • - [x] создаёт отмеченный чекбокс.
  • Можно комбинировать с нумерованными и маркированными списками.

HTML-вывод будет содержать <input type="checkbox">, что позволяет визуально отображать статус задачи.

Автоссылки и mention-формат

GFM автоматически конвертирует URL и email-адреса в кликабельные ссылки:

Посетите https://example.com или отправьте письмо на email@example.com

Markdown-it использует опцию linkify: true для поддержки этой функциональности. Ссылка преобразуется в тег <a href="...">.

Также GFM поддерживает @username для упоминаний. Для этого можно применить кастомный плагин, который заменяет @ на ссылку на профиль пользователя.

Поддержка смайлов и эмодзи

Хотя стандартный GFM не требует эмодзи, расширенные варианты используют короткие коды :smile:, :heart:. Markdown-it поддерживает это через плагин markdown-it-emoji:

const md = new MarkdownIt()
  .use(require('markdown-it-emoji'));

Синтаксис:

I love coding :heart:

Вывод:

I love coding <span class="emoji">❤️</span>

Настройка строгого и мягкого режима

Markdown-it позволяет гибко регулировать совместимость с GFM:

  • Жёсткий режим (strict) — игнорирует нестандартные расширения.
  • Мягкий режим (soft) — включает поддержку таблиц, задач и автоссылок.

Пример:

const md = new MarkdownIt({
  gfm: true,       // включение основных функций GFM
  breaks: true,    // перенос строки как в GFM
  linkify: true
});

Опция breaks: true преобразует одиночный перенос строки в <br>, что соответствует поведению GitHub.

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

Пример таблицы с выравниванием:
| Левый | Центр | Правый |
|:------|:-----:|-------:|
| Текст | Текст  | Текст  |

HTML-результат:

<table>
  <thead>
    <tr>
      <th style="text-align:left">Левый</th>
      <th style="text-align:center">Центр</th>
      <th style="text-align:right">Правый</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align:left">Текст</td>
      <td style="text-align:center">Текст</td>
      <td style="text-align:right">Текст</td>
    </tr>
  </tbody>
</table>
Пример задачного списка:
- [ ] Купить молоко
- [x] Отправить отчет

HTML-результат:

<ul class="task-list">
  <li class="task-list-item"><input type="checkbox"> Купить молоко</li>
  <li class="task-list-item"><input type="checkbox" checked> Отправить отчет</li>
</ul>

Итог

Markdown-it в режиме совместимости с GFM предоставляет полный набор функций для работы с расширенным синтаксисом Markdown. Таблицы, задачи, автоссылки, эмодзи и упрощённый перенос строк делают его идеальным инструментом для интеграции с платформами, поддерживающими GitHub Flavored Markdown. Опции linkify, breaks, gfm и подключение плагинов обеспечивают точное соответствие стандарту и гибкую настройку вывода HTML.

Оглавление