remark-gfm: поддержка GitHub Flavored Markdown

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

Основные возможности GFM

GitHub Flavored Markdown расширяет стандартный Markdown следующими функциями:

  1. Таблицы Позволяют создавать структурированные данные в виде таблиц с выравниванием столбцов. Пример синтаксиса:

    | Имя       | Возраст | Город       |
|-----------|--------:|------------|
| Иван      | 25      | Москва     |
| Екатерина | 30      | Санкт-Петербург |

    В remark-gfm таблицы автоматически распознаются и корректно преобразуются в дерево MDAST.

  2. Зачёркнутый текст Поддержка синтаксиса ~~текст~~ для создания зачёркнутого текста:

    Этот текст ~~не актуален~~.

  3. Авто-ссылки Преобразует URL и email в кликабельные ссылки без явного использования синтаксиса [текст](url):

    https://example.com
user@example.com

    remark-gfm распознаёт такие строки и автоматически создает узлы типа link в MDAST.

  4. Задачные списки (Task Lists) Добавляет поддержку списков с флажками [ ] и [x], которые широко используются в документации и TODO-листах на GitHub:

    - [x] Сделано
- [ ] В процессе
- [ ] Не начато

    В MDAST каждый элемент превращается в listItem с полем checked.

Подключение и использование remark-gfm

Для использования плагина необходимо установить его через npm или yarn:

npm install remark remark-gfm

Базовая интеграция с remark выглядит так:

import { remark } from 'remark';
import gfm from 'remark-gfm';

const markdown = `
| Имя | Возраст |
|-----|--------|
| Алексей | 28 |
- [x] Сделано
`;

remark()
  .use(gfm)
  .process(markdown)
  .then((file) => {
    console.log(String(file));
  });

В результате все GFM-элементы корректно обрабатываются, а структура документа может быть дополнительно модифицирована через другие плагины.

Структура MDAST при использовании GFM

remark-gfm расширяет дерево Markdown AST (MDAST), добавляя специализированные узлы:

  • table — для таблиц
  • tableRow — для строк таблицы
  • tableCell — для ячеек
  • delete — для зачёркнутого текста
  • listItem с полем checked — для задач

Пример MDAST для задачного списка:

{
  "type": "list",
  "ordered": false,
  "children": [
    {
      "type": "listItem",
      "checked": true,
      "children": [{ "type": "paragraph", "children": [{ "type": "text", "value": "Сделано" }] }]
    },
    {
      "type": "listItem",
      "checked": false,
      "children": [{ "type": "paragraph", "children": [{ "type": "text", "value": "В процессе" }] }]
    }
  ]
}

Эта структура позволяет последующим плагинам и преобразователям, таким как rehype, корректно рендерить Markdown в HTML или другие форматы.

Интеграция с Rehype

remark-gfm часто используется в связке с rehype, что позволяет преобразовывать Markdown в HTML с поддержкой GFM:

import { remark } from 'remark';
import gfm from 'remark-gfm';
import remarkRehype from 'remark-rehype';
import rehypeStringify from 'rehype-stringify';

remark()
  .use(gfm)
  .use(remarkRehype)
  .use(rehypeStringify)
  .process(markdown)
  .then((file) => {
    console.log(String(file));
  });

После такой цепочки таблицы, задачи и зачёркнутый текст рендерятся в соответствующие HTML-элементы (<table>, <input type="checkbox">, <del>), полностью повторяя функциональность GFM на GitHub.

Настройка поведения remark-gfm

remark-gfm не требует обязательной конфигурации, но можно управлять обработкой некоторых элементов через опции:

  • singleTilde — позволяет использовать одинарное ~ вместо ~~ для зачёркивания.
  • taskListItems — включает или отключает поддержку задачных списков.

Пример настройки:

remark()
  .use(gfm, { singleTilde: true })
  .process(markdown)

Это позволяет гибко адаптировать поведение плагина под собственные стандарты Markdown.

Совместимость и ограничения

  • Поддержка GFM с remark-gfm полностью соответствует синтаксису GitHub на момент последнего обновления.
  • Некоторые экспериментальные функции GitHub, например расширенные таблицы с rowspan/colspan, не поддерживаются.
  • Работает во всех средах, где доступен Node.js, а также совместима с ESM и CommonJS.

remark-gfm является стандартным выбором для проектов, где требуется полноценная поддержка расширенного Markdown GitHub без ручной обработки синтаксиса.

Оглавление