GFM vs CommonMark vs Pandoc Markdown: сравнение синтаксиса

Markdown выглядит как один язык, пока один и тот же файл не рендерится по-разному в GitHub, Hugo, Obsidian или Pandoc. И проблема не в том, что Markdown ненадежен.

Проблема в том, что термин «Markdown» описывает не единый универсальный формат документов, а целое семейство связанных синтаксисов, парсеров и платформенных возможностей. CommonMark определяет точное переносимое ядро, GitHub Flavored Markdown добавляет функции, полезные для совместной разработки программного обеспечения, а Pandoc Markdown расширяет язык до полноценного формата для подготовки документов.

Выбор между ними зависит от того, где должен рендериться документ. У файла README, поста в блоге Hugo и научной статьи разные требования. Это сравнение является частью более общей документации по инструментам и охватывает формальные диалекты, платформенные расширения и практические правила переносимости, чтобы вы могли выбрать правильный синтаксис для целевой среды. Для быстрого справочника по синтаксису в шпаргалке по Markdown описаны основные элементы форматирования.

Markdown — это не один язык

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

CommonMark был создан, чтобы определить согласованные правила парсинга для фундаментальных структур Markdown. GitHub Flavored Markdown, обычно называемый GFM, построен на этой основе и содержит несколько широко используемых расширений.

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

Упрощенная иерархия выглядит следующим образом:

Эта иерархия полезна, но она не представляет собой точного наследования в каждой реализации. Каждый рендерер может независимо включать, отключать или добавлять синтаксисы.

Краткий ответ

Используйте синтаксис, совместимый с CommonMark, когда переносимость важнее всего.

Используйте GFM при написании файлов README, pull request’ов, шаблонов задач и технической документации, предназначенной преимущественно для платформ, совместимых с GitHub.

Используйте Pandoc Markdown, когда исходный документ должен стать PDF, DOCX, EPUB, LaTeX, слайдами или научной статьёй с цитированиями и метаданными.

Для технического блога на Hugo используйте ядро CommonMark плюс расширения Goldmark, которые явно включены на вашем сайте. Не стоит предполагать, что каждая функция, видимая в GitHub, будет работать просто потому, что Hugo описывается как совместимый с GFM.

Мнение: если вы запомните только одно правило для технического блога на Hugo, то считайте ядро CommonMark плюс таблицы и списки задач в стиле GFM стандартным набором, а всё остальное — сноски, математика, блоки с предупреждениями, атрибуты заголовков — явным, протестированным расширением, а не предполагаемым по умолчанию. Эта единственная привычка предотвращает большинство проблем с переносимостью, описанных ниже.

CommonMark: переносимое ядро

CommonMark — это формальная спецификация для базового языка Markdown. Его главный вклад — не большой набор функций, а согласованный парсинг.

Он определяет, как парсеры должны интерпретировать:

• Абзацы
• Заголовки ATX и Setext
• Блок-цитаты
• Упорядоченные и неупорядоченные списки
• Ограниченные и отступные блоки кода
• Эмфазис и сильный эмфазис
• Ссылки и изображения
• Ссылки в стиле ссылок (reference-style links)
• Инлайн-код
• Разделители тем (thematic breaks)
• Сырые блоки HTML
• Жесткие и мягкие переносы строк

Документ CommonMark по-прежнему может вести себя по-разному на уровне презентации. CSS, подсветка синтаксиса, якоря заголовков, санитизация HTML и политики ссылок находятся за пределами основных правил парсинга.

Поэтому CommonMark следует рассматривать как надежный структурный базис, а не как гарантию того, что каждый рендерер создаст идентичную страницу.

Пример переносимого CommonMark

# Деплой сервиса

Сервис предоставляет небольшой HTTP API.

## Требования

- Linux
- Docker
- 8 ГБ памяти

## Запуск сервиса

```bash
docker compose up -d
```

Подробнее см. в [гаиде по конфигурации](configuration.md).

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

GitHub Flavored Markdown: CommonMark для проектных задач

GitHub Flavored Markdown — это формальный диалект на основе CommonMark. Он сохраняет модель парсинга CommonMark и добавляет функции, обычно необходимые в документации репозиториев и при совместной работе.

Формальная спецификация GFM добавляет:

• Таблицы с пипами (pipe tables)
• Пункты списка задач (task list items)
• Зачеркивание (strikethrough)
• Расширенные автоматические ссылки (autolinks)
• Ограничения на некоторые сырые теги HTML

Эти расширения стали настолько распространенными, что многие пользователи думают, что они являются частью стандартного Markdown. Но они не входят в ядро CommonMark.

Таблицы GFM

| Бэкенд | Лучшее применение |
|---|---|
| Ollama | Локальные эксперименты |
| vLLM | Общий инференс |
| SGLang | Структурированные нагрузки |

Строгий парсер CommonMark имеет право трактовать это как обычный текст абзаца. Совместимый с GFM парсер распознает это как таблицу. Для более глубокого изучения синтаксиса таблиц и вариантов выравнивания см. Таблицы в Markdown.

Списки задач GFM

- [x] Установить Docker
- [x] Скачать модель
- [ ] Добавить мониторинг

Синтаксис списков задач полезен в задачах (issues), pull request’ах и документации проектов. Вне поддерживающего рендерера он может отображаться как обычный список с буквальными квадратными скобками.

Зачеркивание GFM

Используйте ~~старый endpoint~~ новый endpoint.

Зачеркивание широко поддерживается, но это все еще расширение, а не переносимый синтаксис CommonMark.

Автоматические ссылки GFM

GFM распознает больше URL-подобного и email-подобного текста без необходимости использования угловых скобок или явной синтаксической конструкции ссылки.

Посетите https://example.com/docs для деталей.

В строгом CommonMark явные автоматические ссылки используют угловые скобки:

<https://example.com/docs>

Явная форма безопаснее, когда документ должен проходить через неизвестные обработчики Markdown.

GitHub.com поддерживает больше, чем формальный GFM

Частым источником путаницы является предположение, что каждая функция Markdown, видимая в GitHub, принадлежит спецификации GFM.

Это не так.

GitHub.com добавляет платформенную обработку и функции вокруг парсера GFM. В зависимости от контекста GitHub может поддерживать:

• Математические выражения
• Диаграммы Mermaid
• Блоки-предупреждения (Alerts)
• Ссылки на задачи и pull request’ы
• Упоминания пользователей и команд
• Ссылки на коммиты
• Шорт-коды эмодзи
• Сворачиваемые секции HTML
• Предпросмотр цветов
• Репозиторий-относительные ссылки
• Автоматические якоря заголовков

Некоторые из этих функций являются расширениями синтаксиса. Другие — это пост-обработка или интеграция с данными GitHub.

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

Диаграммы Mermaid в GitHub

GitHub рендерит ограниченный блок кода с меткой mermaid как диаграмму:

```mermaid
flowchart LR
    A[Markdown] --> B[Отрендеренная диаграмма]
```

Универсальный рендерер GFM может отобразить тот же блок как подсвеченный исходный код. Markdown остается валидным, но улучшенный рендеринг специфичен для платформы. Для практического введения в синтаксис Mermaid см. Быстрый старт с диаграммами Mermaid.

Математические выражения в GitHub

GitHub поддерживает инлайн и блочные математические выражения, используя разделители в виде доллара и дополнительные формы экранирования.

Размер кэша приблизительно равен $2nlhd$ байт.

$$
C = 2nlhd
$$

Математика не является частью формального GFM. Перенос этого контента в другой рендерер требует совместимого математического расширения, такого как KaTeX, MathJax или поддержка математики Pandoc.

Блоки-предупреждения в GitHub

GitHub поддерживает блок-цитаты в стиле предупреждений, например:

> [!WARNING]
> Изменение этой настройки очищает кэш.

В GitHub это может выглядеть как стилизованное предупреждение. В простом рендерере CommonMark оно обычно выглядит как обычная блок-цитата, содержащая [!WARNING].

Такой фолбэк читаем, что делает блоки-предупреждения GitHub менее опасными, чем расширения, которые исчезают полностью. Тем не менее, это все еще не переносимые элементы презентации.

Pandoc Markdown: Markdown как язык документов

Pandoc Markdown разработан для конвертации документов, а не для конкретного сайта. Он использует Markdown в качестве исходного синтаксиса для создания HTML, PDF, DOCX, EPUB, LaTeX, презентаций и других форматов.

Его читатель Markdown по умолчанию включает большой набор расширений. Важные возможности включают:

• Блоки метаданных YAML
• Сноски
• Цитирования
• Несколько форматов таблиц
• Списки определений
• Математическая нотация
• Идентификаторы и атрибуты заголовков
• Атрибуты блоков кода
• Ограниченные разделы (fenced divisions)
• Скобки для инлайн-элементов (bracketed spans)
• Надстрочные и подстрочные индексы
• Зачеркивание
• Блоки строк (line blocks)
• Нумерованные списки примеров
• Сырой LaTeX
• Сырой HTML
• Автоматическая нумерация разделов
• Обработка библиографии

Pandoc Markdown гораздо более экспрессивен, чем CommonMark или формальный GFM. Эта экспрессивность делает его мощным для издательства, но менее безопасным как формат обмена.

Сноски Pandoc

У Markdown есть несколько несовместимых диалектов.[^dialects]

[^dialects]: CommonMark, GFM и Pandoc Markdown — три
    важных примера.

Синтаксис сносок поддерживается многими современными инструментами, но он не является частью CommonMark или формального GFM.

GitHub в настоящее время рендерит сноски в нескольких контекстах контента, но это платформенная функция GitHub, а не формальная гарантия GFM. Рендерер, заявляющий только о совместимости с CommonMark или GFM, может не поддерживать их.

Цитирования Pandoc

PagedAttention улучшает управление памятью KV cache
[@kwon2023pagedattention].

При наличии файла библиографии и стиля цитирования Pandoc может разрешить это в отформатированную научную ссылку и библиографию.

pandoc article.md \
  --citeproc \
  --bibliography references.bib \
  --csl ieee.csl \
  -o article.pdf

Синтаксис цитирования остается читаемым в неподдерживающем рендерере, но он не станет отформатированной ссылкой без Pandoc или другого совместимого процессора цитирований. Гибкость Pandoc на стороне чтения также лежит в основе конвейеров конвертации в обратном направлении — см. конвертацию документов Word в Markdown для практического примера использования расширенного диалекта Pandoc как промежуточного формата.

Списки определений Pandoc

CommonMark
: Точная спецификация для ядра Markdown.

GFM
: Диалект на основе CommonMark с программно-ориентированными расширениями.

Pandoc Markdown
: Расширенный формат создания документов для конвертации.

Списки определений полезны в инструкциях, глоссариях и технических книгах. Обычно они плохо деградируют в рендерерах, которые не поддерживают их, так как строки с двоеточиями остаются видимыми как обычный текст.

Атрибуты заголовков Pandoc

## Конфигурация кэша {#cache-config .deployment}

Pandoc интерпретирует фигурные скобки как явный идентификатор и список классов. Многие другие рендереры Markdown показывают текст атрибута непосредственно в заголовке.

Это один из самых явных примеров полезного синтаксиса, который не следует помещать в документ, ожидаемый для рендеринга везде.

Ограниченные разделы Pandoc

::: warning
Изменение этой опции перезапускает сервер.

Pandoc преобразует это в структурный раздел с классом. Шаблоны, CSS, фильтры или модули вывода могут решить, как эта структура должна выглядеть.

Большинство рендереров CommonMark и GFM не распознают этот забор (fence). Они отображают двоеточия и содержимое как обычный текст.

CommonMark vs GFM vs Pandoc Markdown

Нижеприведенная матрица описывает формальные диалекты, а не все функции, добавленные GitHub.com, Hugo, Obsidian, GitLab или другой платформой.

Слово «Нет» не означает, что платформа никогда не может поддерживать функцию. Это означает, что функция не гарантируется формальной спецификацией этого диалекта.

Какой синтаксис работает в GitHub?

Для файлов README, задач, pull request’ов, обсуждений и вики GFM является естественной базовой линией.

Обычно можно использовать:

• Синтаксис CommonMark
• Таблицы
• Списки задач
• Зачеркивание
• Расширенные автолинки
• Блоки кода с подсветкой синтаксиса
• Специфичные для GitHub ссылки
• Поддерживаемую GitHub математику
• Поддерживаемые GitHub диаграммы
• Блоки-предупреждения GitHub
• Сноски, если они поддерживаются поверхностью контента

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

Для файлов репозитория, которые также публикуются где-то еще, тестируйте исходный код во втором рендерере, а не рассматривайте предпросмотр GitHub как авторитетный источник.

Какой синтаксис работает в Hugo?

Hugo использует Goldmark в качестве рендерера Markdown по умолчанию. Goldmark соответствует CommonMark и предоставляет расширения, совместимые с важными частями GFM.

В типичной конфигурации Hugo хорошо работают:

• Структура CommonMark
• Ограниченные блоки кода
• Таблицы с пипами
• Зачеркивание
• Списки задач
• Автоматические ID заголовков
• Подсветка синтаксиса
• Сноски, если расширение включено
• Списки определений, если включено
• Типографские замены, если включено

Hugo также добавляет функции за пределами Markdown через:

• Front matter
• Шорт-коды
• Хуки рендеринга (render hooks)
• Ресурсы страниц
• Функции внутренних ссылок
• Обработку шаблонов
• Конфигурацию сайта

Эти функции Hugo не перемещаются вместе с файлом Markdown. Для практического примера деплоя Hugo см. Деплой Hugo в AWS S3.

Front matter Hugo — это не содержимое Markdown

Страница Hugo часто начинается с метаданных в YAML, TOML или JSON:

---
title: "Совместимость Markdown"
description: "Сравнение диалектов Markdown и рендереров."
date: 2026-07-31
tags:
  - Markdown
  - documentation
---

Pandoc также может распознавать блоки метаданных YAML, но он интерпретирует поля согласно своим шаблонам и модулям вывода. GitHub обычно отображает блок как секцию в стиле YAML или рассматривает его как метаданные репозитория только в определенных системах.

Таким образом, один и тот же синтаксис может распознаваться более чем одним инструментом, не имея одинаковой семантики.

Сырой HTML в Hugo

Goldmark по умолчанию не рендерит потенциально небезопасный сырой HTML в стандартной конфигурации Hugo.

Блок, такой как:

<div class="notice">
  Перезапустите сервис после изменения этого значения.
</div>

может быть опущен, если рендеринг сырого HTML не включен или контент не реализован через шорт-код или хук рендеринга.

Для контролируемого технического блога включение сырого HTML может быть разумным. Тем не менее, это делает исходный код менее переносимым, и это должно быть осознанным решением на уровне сайта.

Mermaid в Hugo

Ограниченный блок mermaid все еще является просто блоком кода, пока тема Hugo, хук рендеринга, шорт-код или JavaScript-конвейер не преобразуют его в диаграмму.

Таким образом, GitHub и Hugo могут принимать одинаковый исходный код Mermaid, используя при этом совершенно разные механизмы рендеринга.

Какой синтаксис работает в Pandoc?

Pandoc может читать несколько диалектов Markdown явно:

pandoc --from=markdown input.md
pandoc --from=commonmark input.md
pandoc --from=gfm input.md
pandoc --from=commonmark_x input.md

Это одна из самых полезных возможностей переносимости Pandoc. Оператор может сообщить Pandoc, какой диалект использует источник, вместо того чтобы полагаться на расплывчатое расширение файла .md.

Pandoc также позволяет включать или отключать отдельные расширения:

pandoc \
  --from=markdown-footnotes-pipe_tables \
  input.md \
  -o output.html

Или начать с более узкого формата и добавить одну функцию:

pandoc \
  --from=commonmark+footnotes \
  input.md \
  -o output.html

Вы можете просмотреть доступные расширения с помощью:

pandoc --list-extensions=markdown
pandoc --list-extensions=commonmark
pandoc --list-extensions=gfm

Эта модель расширений мощна, но это означает, что «Pandoc Markdown» — не всегда одна фиксированная конфигурация. Команды сборки и файлы настроек по умолчанию являются частью спецификации документа.

Какой синтаксис работает в Obsidian?

Obsidian хранит заметки как файлы Markdown, но его модель создания включает несколько прикладных функций.

Общие примеры включают:

• Вики-ссылки
• Встроенные заметки
• Встроенные файлы
• Блоки-вызовы (Callouts)
• Ссылки на блоки
• Теги
• Свойства (Properties)
• Подсветка
• Комментарии
• Запросы Dataview из плагинов
• Прикладные URI-ссылки

Вики-ссылка, такая как:

[[Совместимость Markdown]]

имеет смысл внутри хранилища Obsidian. GitHub, CommonMark и читатель Pandoc по умолчанию обычно отображают ее как буквальную текст в скобках.

Встраивание (embed) еще более прикладное:

![[compatibility-table]]

Ссылочное содержимое не присутствует в самом файле. Таким образом, экспорт или публикация заметки требуют шага развёртки, который разрешает встраивание.

Obsidian — хороший пример того, почему хранение в файлах .md не гарантирует переносимость Markdown. Для практического взгляда на Obsidian как инструмент управления знаниями см. Obsidian для персонального управления знаниями.

Какой синтаксис работает в GitLab?

GitLab Flavored Markdown использует CommonMark в качестве ядра и включает функции GFM, такие как таблицы и списки задач. Затем он добавляет специфичное для GitLab поведение, включая перекрестные ссылки, математическую нотацию, диаграммы и другие функции совместной работы.

README, написанный на консервативном GFM, обычно перемещается между GitHub и GitLab без серьезных повреждений.

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

Матрица поддержки платформ

Эта матрица описывает обычное поведение по умолчанию. Темы, плагины, расширения и конфигурация могут изменять отдельные ячейки.

«Да» все еще не гарантирует идентичный HTML или визуальную презентацию. Это означает, что среда распознает общую функцию.

Синтаксис, который обычно безопасен везде

Самый безопасный переносимый подмножество включает:

• Заголовки ATX, использующие #
• Обычные абзацы
• Пустые строки между блоками
• - для неупорядоченных списков
• 1. для упорядоченных списков
• Ограниченные блоки кода с использованием обратных кавычек
• Инлайн-код с использованием обратных кавычек
• Эмфазис с использованием *text*
• Сильный эмфазис с использованием **text**
• Обычные ссылки
• Обычные изображения
• Блок-цитаты
• Разделители тем
• Явные автолинки с угловыми скобками

Намеренно консервативный документ может выглядеть так:

# Руководство по деплою

Это руководство объясняет, как деплоить сервис.

## Требования

- Docker
- Linux
- Поддерживаемая GPU

## Конфигурация

Создайте файл с именем `compose.yaml`.

```yaml
services:
  application:
    image: example/application:1.0
```

Для получения дополнительной информации см. [справочник по конфигурации](config.md).

> Сделайте резервную копию существующих данных перед обновлением.

Этот синтаксис хорошо переносится, потому что он не зависит от таблиц, сносок, атрибутов, блоков-вызовов или платформенной обработки.

Синтаксис, который часто ломается

Проблемы переносимости склонны聚类 around небольшому числу функций.

Таблицы с пипами

Таблицы с пипами хорошо поддерживаются инструментами, ориентированными на GFM, но не строгим CommonMark.

Таблица может деградировать в нечитаемый текст, если она проходит через парсер, который не распознает ее. Для высокопереносимых документов рассмотрите короткие списки или семантический HTML, сгенерированный на этапе сборки.

Сноски

Синтаксис сносок стал распространенным, но остается расширением.

Разные инструменты могут:

• Поддерживать только один формат сносок
• Размещать сноски по-разному
• Генерировать разные идентификаторы
• Отклонять многоабзацные сноски
• Рендерить источник буквально

Используйте сноски, когда издательский конвейер известен. Избегайте зависимости от них в файлах README, которые должны рендериться на произвольных системах.

ID и атрибуты заголовков

Этот синтаксис Pandoc не переносим:

## Установка {#installation .procedure}

Используйте обычный заголовок и позвольте рендереру сгенерировать собственный якорь, когда переносимость важна.

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

Блоки-вызовы и предупреждения

GitHub, Obsidian, GitLab, MkDocs, Docusaurus и темы Hugo могут поддерживать блоки, похожие на вызовы (callout), но они часто используют разный синтаксис.

Переносимый фолбэк — это обычная блок-цитата:

> Внимание: Сделайте резервную копию базы данных перед обновлением.

Она менее визуально впечатляющая, но сохраняет смысл везде.

Вики-ссылки

Вики-ссылки лаконичны внутри инструментов управления знаниями:

[[KV Cache]]

Они плохо подходят для обмена синтаксисом, потому что путь к цели, имя файла, правила заголовков и поведение разрешения принадлежат приложению.

Используйте стандартные ссылки Markdown в контенте, предназначенном для публикации:

[KV cache](kv-cache.md)

Сырой HTML

Сырой HTML — это обычный аварийный выход, когда Markdown не может выразить макет. Это также частая проблема переносимости и безопасности.

Рендерер может:

• Удалять HTML
• Экранировать его
• Санитизировать выбранные элементы
• Позволять блоки, но не инлайн-элементы
• Отказываться от парсинга Markdown внутри HTML
• Проходить его без изменений только в доверенном режиме

Используйте сырой HTML только тогда, когда цель публикации контролируется.

Математическая нотация

Математика, разделенная долларами, популярна, но не интерпретируется универсально.

Исходник:

Сложность составляет $O(n^2)$.

может стать:

• Отрендеренной математикой
• Обычным текстом со знаками доллара
• Неправильным эмфазисом
• Входом для другого математического парсера

Выберите один математический конвейер и протестируйте его в каждой целевой среде.

Mermaid и другие блоки диаграмм

Забора кода Mermaid синтаксически безопасен, потому что неподдерживающие рендереры обычно отображают его как код.

Семантический результат все еще отличается. Читатели могут видеть отрендеренную архитектурную диаграмму в GitHub и исходный код Mermaid в другой среде.

Это плавная деградация, а не истинная совместимость.

Три слоя совместимости Markdown

Полезно разделять совместимость на три слоя.

Слой 1: Совместимость парсинга

Распознает ли парсер структуру?

Примеры включают заголовки, таблицы, сноски и ограниченные разделы.

Слой 2: Совместимость трансформации

Применяет ли платформа дополнительную обработку?

Примеры включают:

• Рендеринг Mermaid
• Разрешение цитирований
• Развертывание вики-ссылок
• Связывание номеров задач
• Обработка шорт-кодов
• Генерацию оглавления

Слой 3: Совместимость презентации

Выглядит ли результат и ведет ли себя он надлежащим образом?

Примеры включают:

• Стилизацию таблиц
• Подсветку синтаксиса
• Цвета предупреждений
• Якоря заголовков
• Адаптивные изображения
• Размещение сносок
• Математические шрифты

Две платформы могут парсить идентичный синтаксис, создавая при этом существенно разную презентацию.

Лучшая модель переносимости

Вместо того чтобы спрашивать, является ли файл «валидным Markdown», задайте четыре более узких вопроса:

1. В каком диалекте написан источник?
2. Какой парсер его читает?
3. Какие расширения включены?
4. Какие платформенные трансформации выполняются после этого?

Например:

Диалект: CommonMark плюс таблицы GFM
Парсер: Goldmark
Расширения: таблицы, зачеркивание, списки задач, сноски
Платформа: Hugo
Дополнительная обработка: хуки рендеринга и JavaScript Mermaid

Это описание гораздо полезнее, чем утверждение «сайт использует Markdown».

Выбор диалекта по случаю использования

Файлы README

Используйте GFM.

Файлы README выигрывают от:

• Таблиц
• Списков задач
• Ограниченного кода
• Автолинков
• Зачеркивания
• Ссылок GitHub

Избегайте чрезмерной зависимости от функций, доступных только в GitHub, когда репозиторий зеркалится в GitLab, рендерится в реестре пакетов или включается в сгенерированную документацию.

Технические статьи на Hugo

Используйте Markdown, совместимый с CommonMark, с документированным набором расширений Goldmark.

Таблицы, заборы кода, сноски и Mermaid могут быть разумными, так как вы контролируете конвейер сборки. Предпочитайте шорт-коды Hugo или хуки рендеринга встраиванию больших объемов сырого HTML.

Держите специфичный для Hugo синтаксис изолированным и легко находимым.

Научные документы

Используйте Pandoc Markdown.

Цитирования, обработка библиографии, сноски, метаданные, математическая нотация, перекрестные ссылки и конвертация в PDF или DOCX оправдывают сниженную переносимость.

Храните команду Pandoc, файл настроек по умолчанию, фильтры, библиографию и шаблоны рядом с исходным кодом. Сам файл источника не полностью описывает сборку.

Книги и длинная документация

Pandoc Markdown обычно является сильнейшим из трех вариантов, когда важно несколько форматов вывода.

Списки определений, цитирования, атрибуты, метаданные и структурированные трансформации становятся важнее по мере роста сложности документа.

Для веб-документации, размещаемой в Git-репозитории, GFM или генератор документации на основе CommonMark может остаться проще.

Заметки и персональные базы знаний

Используйте нативный синтаксис выбранного приложения для заметок, когда прикладные функции предоставляют реальную ценность.

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

Общая документация между неизвестными системами

Используйте консервативный подмножество CommonMark.

Избегайте:

• Вики-ссылок
• Платформенных предупреждений
• Атрибутов заголовков
• Цитирований
• Сырого HTML
• Пользовательских контейнеров
• Прикладных встраиваний
• Шорт-кодов

Переносимость обычно требует отказа от удобных функций.

Практические правила для переносимого Markdown

Начинайте со структуры CommonMark

Используйте CommonMark для каркаса документа:

• Заголовки
• Абзацы
• Списки
• Ссылки
• Изображения
• Блок-цитаты
• Блоки кода

Это обеспечивает выживание основного смысла даже при сбое необязательных расширений.

Добавляйте функции GFM осознанно

Таблицы и списки задач разумны, если все важные цели их поддерживают.

Не предполагайте, что «большинство инструментов поддерживают GFM», без тестирования точной цели. Некоторые заявляют о совместимости с GFM, включая только выбранные расширения.

Изолируйте платформенные расширения

Держите специфичный для платформы синтаксис в четко идентифицируемых блоках.

Например, централизуйте шорт-коды Hugo, цитирования Pandoc или встраивания Obsidian, а не разбрасывайте их по каждому абзацу.

Изоляция облегчает последующую конвертацию.

Предпочитайте плавную деградацию

Блок Mermaid деградирует в читаемый исходный код. Предупреждение GitHub деградирует в блок-цитату.

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

Выбирайте расширения, чей фолбэк остается понятным.

Не полагайтесь на автоматически сгенерированные ID заголовков

Алгоритмы якорей заголовков различаются между GitHub, Hugo, Pandoc и генераторами документации.

Для перекрестных ссылок между документами используйте явные ID, поддерживаемые рендерером, только когда целевой конвейер контролируется. Иначе ссылайтесь на документ, а не на сгенерированный фрагмент.

Храните конфигурацию сборки с контентом

Расширения Pandoc, настройки Hugo, плагины, фильтры и интеграции JavaScript определяют, как работает Markdown.

Коммитьте соответствующие файлы конфигурации вместе с исходным кодом:

content/
  article.md
pandoc.yaml
references.bib
config/
  _default/
    markup.yaml
layouts/
  _default/
    _markup/

Одноразовое расширение .md не фиксирует издательскую среду. Для структурированного подхода к документированию этих решений см. Записи решений для AI-управляемой разработки.

Тестируйте Markdown на всех важных целях

Визуальный предпросмотр в одном редакторе недостаточен. Редактор может поддерживать более богатый диалект, чем продакшен-рендерер.

Для Pandoc тестируйте явные входные форматы:

pandoc --from=commonmark article.md -o commonmark.html
pandoc --from=gfm article.md -o gfm.html
pandoc --from=markdown article.md -o pandoc.html

Предупреждения и видимые знаки препинания источника раскрывают, какие функции специфичны для диалекта.

Для Hugo соберите продакшен-сайт:

hugo --gc --minify

Затем проверяйте сгенерированный HTML, а не полагаться только на предпросмотр редактора.

Для репозиториев просматривайте закоммиченный файл на фактической хостинг-платформе. Локальные расширения Markdown в VS Code могут не соответствовать GitHub или GitLab.

Устранение распространенных несоответствий рендеринга

Когда файл, который работал на одной платформе, ломается на другой, сбой обычно попадает в один из нескольких повторяемых шаблонов. Нижеприведенная таблица перечисляет симптом таким, каким вы его фактически видите, наиболее вероятную причину и конкретную команду или проверку для подтверждения и исправления.

Это самый быстрый первый прогон перед тем, как предположить «баг» в Markdown — большинство этих несоответствий являются отсутствующим расширением или платформенно-специфичной функцией, а не сломанным синтаксисом. Для проблем, специфичных для заборов кода, таких как отсутствие подсветки синтаксиса или неподдерживаемые идентификаторы языков, см. специальное руководство по блокам кода в Markdown.

Линт переносимого подмножества

Линтер Markdown не может гарантировать совместимость рендерера, но он может устранить неизбежную неоднозначность.

Полезные правила включают:

• Используйте согласованные стили заголовков
• Добавляйте пустые строки вокруг списков и блоков кода
• Используйте ограниченные блоки кода, а не отступные
• Указывайте языки заборов кода
• Избегайте пропущенных уровней заголовков
• Используйте согласованные маркеры списков
• Избегайте неоднозначного эмфазиса вокруг знаков препинания
• Сохраняйте согласованные окончания строк
• Валидируйте ссылки и изображения

Для публикации на нескольких целях добавьте тест сборки для каждого важного рендерера, а не полагаться только на синтаксический линт.

Конвертация между диалектами с помощью Pandoc

Pandoc может нормализовать документы из одного диалекта в другой:

pandoc \
  --from=markdown \
  --to=gfm \
  article.md \
  -o article-gfm.md

Или конвертировать GFM в Pandoc Markdown:

pandoc \
  --from=gfm \
  --to=markdown \
  README.md \
  -o document.md

Это полезно, но конвертация не гарантирует сохранение каждой функции.

Потенциальные потери включают:

• Платформенно-специфичные ссылки
• Стилизацию блоков-вызовов
• Сложные таблицы
• Встроенные прикладные объекты
• Пользовательские атрибуты
• Поведение сырого HTML
• Синтаксис плагинов
• Рендеринг диаграмм
• Точное пробельное пространство и форматирование

Pandoc сохраняет структуру документа лучше, чем исходное форматирование. Рассматривайте конвертацию как шаг сборки, а не как обратимый текстовый форматтер.

Рекомендуемая стратегия для сайтов Hugo

Для технического блога на Hugo самой практической политикой является:

1. Используйте CommonMark для основного текста и структуры.
2. Включите небольшой документированный набор расширений Goldmark.
3. Используйте таблицы и списки задач в стиле GFM, где они улучшают читаемость.
4. Реализуйте Mermaid через один согласованный хук рендеринга или шорт-код.
5. Обрабатывайте математику через один документированный конвейер KaTeX или MathJax.
6. Используйте front matter Hugo только в начале файлов контента.
7. Предпочитайте хуки рендеринга и шорт-коды сырому HTML.
8. Держите исходные ссылки как стандартные ссылки Markdown, где возможно.
9. Тестируйте мигрированные или полученные извне документы через Hugo.
10. Документируйте любой синтаксис, который не будет корректно рендериться в GitHub.

Этот подход принимает, что контент Hugo не является универсально переносимым, сохраняя при этом границу переносимости видимой.

Худший подход — случайное смешение диалектов: блоки-предупреждения GitHub, встраивания Obsidian, атрибуты Pandoc и шорт-коды Hugo, размещенные в одном документе без определенного конвейера сборки.

Таблица решений

Заключение

CommonMark, GitHub Flavored Markdown и Pandoc Markdown — это не конкурирующие версии одного продукта. Они решают разные проблемы.

CommonMark обеспечивает надежную основу парсинга. GFM добавляет практические функции для совместной разработки программного обеспечения, тогда как Pandoc Markdown превращает Markdown в богатый исходный язык для публикации и конвертации.

Самое безопасное правило простое: пишите в наименьшем диалекте, который удовлетворяет реальной цели. Используйте CommonMark, когда контент должен перемещаться, GFM, когда целевая аудитория — это коллаборация в стиле GitHub, и Pandoc Markdown, когда структура документа и форматы вывода важнее универсального рендеринга.

Переносимость Markdown достигается не путем избегания каждого расширения. Она достигается путем знания, какие расширения являются частью исходного контракта, и тестирования их в каждом рендерере, который имеет значение.

Ссылки

• Спецификация CommonMark
• Спецификация GitHub Flavored Markdown
• Pandoc Markdown
• Документация Goldmark
• Конфигурация Goldmark в Hugo
• Написание математических выражений в GitHub