GitHub Flavored Markdown

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

История

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

Оригинальный Markdown был создан Джоном Грубером и Аароном Шварцем в 2004 году как простой язык разметки для преобразования текста в HTML. Однако его синтаксис, особенно в части таблиц, списков и форматирования кода, оставлял много неоднозначностей. Разные реализации Markdown (например, Pandoc, MultiMarkdown, CommonMark) интерпретировали одни и те же конструкции по-разному, что затрудняло переносимость документов.

Разработка и стандартизация

В 2013 году GitHub представил собственную версию Markdown, получившую название GitHub Flavored Markdown. Основной целью было устранение неоднозначностей и добавление функций, необходимых для работы с кодом: подсветка синтаксиса, автоматическое создание ссылок на issue и коммиты, поддержка таблиц и зачёркивания текста. В 2017 году GitHub опубликовал официальную спецификацию GFM, основанную на стандарте CommonMark, но с рядом расширений. Спецификация GFM официально документирована и поддерживается в актуальном состоянии.

Отличия от стандартного Markdown

Поддержка CommonMark

GFM базируется на спецификации CommonMark, которая строго определяет синтаксис Markdown. Это означает, что все конструкции, описанные в CommonMark, работают в GFM идентично. Основные отличия GFM от классического Markdown (по версии Грубера) включают:

• Таблицы: GFM поддерживает создание таблиц с помощью символов | и -.
• Зачёркивание: текст, заключённый в двойные тильды (~~текст~~), отображается зачёркнутым.
• Автоссылки: URL-адреса автоматически преобразуются в кликабельные ссылки без необходимости заключать их в угловые скобки.
• Подсветка синтаксиса: в блоках кода можно указать язык программирования, и GFM автоматически подсветит синтаксис.
• Списки задач: элементы списка, начинающиеся с - [ ] или - [x], отображаются как флажки (чекбоксы), которые можно отмечать в интерфейсе.

Дополнительные возможности

• Автоматическая ссылка на issue и пул-реквесты: написание #123 автоматически создаёт ссылку на issue или пул-реквест с номером 123 в текущем репозитории.
• Ссылки на пользователей: @username создаёт упоминание пользователя, что отправляет ему уведомление.
• Ссылки на коммиты: SHA-хеш коммита (например, abc1234) автоматически преобразуется в ссылку на соответствующий коммит.
• Эмодзи: GFM поддерживает вставку эмодзи как через текстовые коды (:smile:), так и через Unicode-символы.

Синтаксис

Таблицы

Таблицы создаются с помощью символов | для разделения столбцов и - для разделения заголовка и тела таблицы. Двоеточия в строке разделителя задают выравнивание текста в столбце:

• :--- — выравнивание по левому краю;
• :---: — выравнивание по центру;
• ---: — выравнивание по правому краю.

Пример: ```

``` Отображается как таблица с тремя столбцами.

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

Текст, заключённый в двойные тильды (~~), отображается зачёркнутым. Используется для обозначения устаревшей или исправленной информации.

Списки задач

Список задач создаётся с помощью маркированного списка, где каждый элемент начинается с - [ ] (невыполненная задача) или - [x] (выполненная задача). В интерфейсе GitHub такие элементы отображаются как флажки, которые можно отмечать кликом.

Блоки кода с подсветкой синтаксиса

Для создания блока кода с подсветкой синтаксиса используется тройные обратные кавычки (``) с указанием языка программирования после открывающих кавычек. Пример: `python def hello(): print("Hello, World!") `` Поддерживаются десятки языков программирования, включая Python, JavaScript, C++, Java, Ruby, Go и другие.

Автоссылки

GFM автоматически преобразует URL-адреса в ссылки, даже если они не заключены в угловые скобки. Также автоматически ссылаются:

• Номера issue и пул-реквестов (#123);
• Упоминания пользователей (@username);
• SHA-хеши коммитов (например, abc1234);
• Ссылки на репозитории в формате owner/repo.

Применение

Документация проектов

GFM является основным языком разметки для файлов README, которые отображаются на главной странице каждого репозитория. Разработчики активно используют GFM для создания документации, руководств, списков изменений (CHANGELOG) и файлов CONTRIBUTING.

Обсуждения и комментарии

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

Вики-страницы

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

Интеграция с другими сервисами

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

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

Отсутствие поддержки сложных таблиц

GFM поддерживает только простые таблицы без объединения ячеек (colspan/rowspan). Для более сложных таблиц требуется использование HTML-тегов, что нарушает единообразие разметки.

Ограниченная поддержка изображений

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

Зависимость от платформы

Хотя GFM является открытой спецификацией, её полная реализация (включая автоматические ссылки на issue и упоминания пользователей) работает только на платформе GitHub. При переносе документов на другие системы часть функциональности может быть потеряна.

Проблемы с безопасностью

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

Интересные факты

• Спецификация GFM была опубликована в 2017 году и с тех пор регулярно обновляется.
• GFM поддерживает более 200 языков программирования для подсветки синтаксиса.
• В GFM можно использовать как текстовые коды эмодзи (:smile:), так и Unicode-символы, но текстовые коды предпочтительнее для совместимости.
• GFM является одним из самых популярных диалектов Markdown, используемых в разработке программного обеспечения.

Источники

• Спецификация GitHub Flavored Markdown (GitHub, 2017)
• CommonMark Specification (CommonMark, 2014–2023)
• Документация GitHub по Markdown (GitHub Docs)
• Статья «GitHub Flavored Markdown» в Википедии (английская версия)