CommonMark

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

История

Предпосылки создания

Язык разметки Markdown был создан Джоном Грубером и Аароном Шварцем в 2004 году как инструмент для написания текстов, которые легко читаются в исходном виде и могут быть преобразованы в структурно валидный HTML. Однако первоначальная спецификация Грубера была неформальной и содержала множество неоднозначностей. Это привело к появлению десятков различных реализаций парсеров (например, PHP Markdown Extra, GitHub Flavored Markdown, Pandoc, Kramdown), каждая из которых по-своему интерпретировала сложные случаи разметки.

Процесс стандартизации

В 2012 году группа разработчиков, включая Джона Макфарлейна (автора Pandoc), Джеффа Этвуда (сооснователя Stack Overflow) и других участников, начала работу над созданием единого стандарта. Проект получил название CommonMark. Основные цели включали:

• Разработку формальной грамматики с использованием синтаксических диаграмм.
• Создание обширного набора тестов (около 600 тестовых примеров) для проверки соответствия парсеров спецификации.
• Обеспечение обратной совместимости с наиболее распространёнными вариантами Markdown, используемыми в сообществе.

В 2014 году была выпущена первая стабильная версия спецификации CommonMark (версия 0.25). В 2017 году вышла версия 0.28, которая стала основой для многих современных реализаций. На 2025 год актуальной является версия 0.31.2, выпущенная в 2022 году.

Основные принципы и отличия от оригинального Markdown

Устранение неоднозначностей

Главное отличие CommonMark от оригинального Markdown Грубера — это формальная спецификация, которая однозначно определяет поведение парсера в любом, даже самом сложном случае. Например, в оригинальном Markdown было неясно, как обрабатывать вложенные списки, сочетание списков и блоков кода или многострочные элементы. CommonMark вводит чёткие правила приоритетов и контекстной обработки.

Синтаксические правила

CommonMark сохраняет базовый синтаксис Markdown, но уточняет и расширяет его. Ключевые правила включают:

• Блоки кода: Для блоков кода используются строки с отступом в 4 пробела или 1 табуляцию, а также «ограждённые блоки кода» (fenced code blocks) с использованием трёх обратных апострофов ( ` ) или тильд (~~~). Ограждённые блоки позволяют указывать язык программирования для подсветки синтаксиса.
• Заголовки: Поддерживаются два стиля: Setext (подчёркивание знаками = или -) и Atx (решетки #). CommonMark уточняет, что после закрывающих решёток в Atx-заголовках не должно быть пробелов.
• Списки: Маркированные списки начинаются с -, * или +. Нумерованные списки — с числа, за которым следует точка. CommonMark вводит правила для определения того, когда список заканчивается (например, пустая строка или элемент другого типа).
• Ссылки и изображения: Синтаксис ссылок ([текст](url)) и изображений (![alt](url)) остаётся стандартным. CommonMark уточняет правила экранирования символов внутри ссылок.
• Эмфазис: Для выделения текста используются звёздочки () или подчёркивания (_). CommonMark вводит правила для определения того, какой символ является открывающим, а какой — закрывающим, что предотвращает неоднозначности (например, в слове foobar).

Формальная грамматика

Спецификация CommonMark включает формальную грамматику, описанную с помощью синтаксических диаграмм. Это позволяет автоматически генерировать парсеры для различных языков программирования, гарантируя их соответствие стандарту.

Реализации и распространение

Парсеры

CommonMark реализован в виде парсеров для многих языков программирования. Наиболее известные реализации:

• cmark: Эталонная реализация на языке C, разработанная авторами спецификации. Она используется как основа для многих других парсеров.
• commonmark.js: Реализация на JavaScript, широко используемая в веб-приложениях.
• Python-Markdown: Одна из популярных реализаций на Python, которая может быть настроена на использование CommonMark.
• Pandoc: Универсальный конвертер документов, который поддерживает CommonMark как входной и выходной формат.

Использование в платформах

CommonMark стал основой для многих современных платформ, где используется Markdown:

• GitHub: В 2017 году GitHub перешёл на собственную реализацию GitHub Flavored Markdown (GFM), которая базируется на CommonMark. GFM расширяет CommonMark дополнительными возможностями, такими как таблицы, зачёркивание текста, списки задач и автоматические ссылки.
• Stack Overflow: Платформа использует CommonMark для форматирования вопросов и ответов.
• Reddit: В 2021 году Reddit перешёл на новый редактор, основанный на CommonMark, что значительно улучшило единообразие форматирования.
• GitLab, Bitbucket, Notion, Obsidian: Многие другие платформы и инструменты для работы с текстом также используют CommonMark или его расширения.

Критика и ограничения

Несмотря на широкое распространение, CommonMark подвергается критике по нескольким направлениям:

• Сложность: Формальная спецификация CommonMark значительно сложнее, чем оригинальная неформальная документация Грубера. Это может затруднить её понимание для новичков.
• Отсутствие некоторых функций: CommonMark не включает в себя некоторые популярные расширения Markdown, такие как таблицы, сноски, математические формулы (LaTeX) или диаграммы. Эти функции реализуются в виде отдельных расширений (например, GFM, Pandoc Markdown).
• Обратная совместимость: Некоторые изменения в синтаксисе CommonMark привели к тому, что старые документы, написанные для оригинального Markdown, могут отображаться некорректно. Однако разработчики CommonMark стремятся минимизировать такие несовместимости.

Значение

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

Источники

1. Спецификация CommonMark (версия 0.31.2) — commonmark.org
2. GitHub Flavored Markdown Spec — github.github.com/gfm
3. MacFarlane, J., et al. "CommonMark: A Formal Specification for Markdown." (2014)
4. Документация Pandoc — pandoc.org
5. Статья "The Markdown Standardization Problem" на сайте Stack Overflow Blog