$ sudo teach IT

Markdown часто воспринимают как универсальный формат: написал один раз — и везде выглядит одинаково. На практике это не совсем так. GitHub и GitLab используют Markdown по-разному, и эти различия регулярно становятся источником неожиданностей.

В этом лонгриде мы разберём, как Markdown отображается в GitHub и GitLab, чем отличается их рендеринг и на какие моменты стоит обращать внимание, чтобы README и документация выглядели предсказуемо.

Что вы узнаете в этом уроке

После чтения вы:

  • поймёте, как GitHub и GitLab рендерят Markdown;
  • узнаете, почему один и тот же файл может выглядеть по-разному;
  • разберётесь с частыми «сюрпризами» при отображении;
  • научитесь писать Markdown, который корректно выглядит в обоих сервисах.

Ключевые термины

Зафиксируем основные понятия:

  • Рендеринг Markdown — процесс преобразования текста Markdown в HTML
  • GitHub Flavored Markdown (GFM) — расширение Markdown, используемое GitHub
  • Диалект Markdown — конкретная реализация и набор поддерживаемых возможностей
  • Платформо-зависимое отображение — различия во внешнем виде одного и того же Markdown

Почему Markdown выглядит по-разному

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

Причина проста: Markdown — это не строгий стандарт, а набор договорённостей. Есть базовый синтаксис, который понимают почти все платформы, но дальше каждая среда интерпретирует его по-своему. Кто-то добавляет удобные расширения, кто-то, наоборот, вводит ограничения.

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

GitHub и GitLab — два ярких примера этой разницы. Формально оба «поддерживают Markdown», но под капотом у них разные механизмы. Они:

  • используют разные движки рендеринга;
  • по-разному трактуют отдельные элементы разметки;
  • поддерживают не одинаковый набор расширений и возможностей.

В результате один и тот же README.md может выглядеть аккуратно и собранно в GitHub, но слегка «поехать» в GitLab — или наоборот. Где-то изменится отступ списка, где-то иначе отобразится таблица, а где-то неожиданно перестанет работать HTML-вставка.

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

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

Вот расширенный вариант с пояснениями и наглядными примерами, в том же спокойном учебном стиле 👇

GitHub Flavored Markdown: что в нём особенного

GitHub использует собственный диалект Markdown — GitHub Flavored Markdown (GFM). По сути, это обычный Markdown, к которому добавили набор практичных расширений, ориентированных на работу с репозиториями и командной разработкой.

Важно понимать: GFM не ломает базовый синтаксис. Он просто расширяет его там, где разработчики чаще всего сталкиваются с неудобствами. Именно поэтому README на GitHub часто выглядит более «живым» и функциональным, даже если автор не задумывался о форматировании.

Рассмотрим ключевые особенности GFM на примерах.

Автоматическое распознавание ссылок и issue

В GitHub достаточно написать номер задачи или pull request, и он автоматически превратится в ссылку:

Исправление связано с задачей #123

GitHub сам понимает, что #123 — это issue или PR в текущем репозитории, и делает кликабельную ссылку. В обычном Markdown такой возможности нет — это именно расширение GFM.

Для README и обсуждений это очень удобно: не нужно вручную вставлять ссылки и отвлекаться от текста.

Таблицы «из коробки»

GitHub поддерживает таблицы без каких-либо дополнительных расширений. Например:

| Команда        | Назначение            |
|---------------|-----------------------|
| mytool init   | Инициализация проекта |
| mytool run    | Запуск обработки      |

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

Зачёркнутый текст

GFM поддерживает зачёркивание с помощью двойных тильд:

~~устаревшая команда~~

Это часто используют, чтобы показать:

  • устаревшие инструкции;
  • больше не поддерживаемые параметры;
  • временно отключённые возможности.

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

Чекбоксы в списках задач

Одна из самых популярных возможностей GFM — списки задач с чекбоксами:

- [x] Настроить окружение
- [ ] Добавить логирование
- [ ] Написать тесты

В GitHub такие списки отображаются как интерактивные чекбоксы. Их часто используют в README, issue и pull request, чтобы показать статус задач или план работ.

Кодовые блоки и подсветка синтаксиса

GFM очень хорошо работает с кодовыми блоками. Достаточно указать язык после трёх обратных кавычек:

```bash
npm install
npm run start

GitHub автоматически применит подсветку синтаксиса, что сильно повышает читаемость примеров команд и кода.

Что это значит на практике

За счёт всех этих расширений Markdown на GitHub выглядит богаче и «умнее» даже без дополнительных усилий со стороны автора. Многие вещи, которые в других средах требуют аккуратной ручной работы, здесь работают автоматически.

Однако важно помнить: GFM — это диалект, а не универсальный стандарт. То, что выглядит идеально в GitHub, может работать иначе или не работать вовсе в других системах.

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

GitLab Markdown: сходства и отличия

GitLab тоже активно использует Markdown, но важно понимать: его реализация не является копией GitHub Flavored Markdown. На первый взгляд различия незаметны, но при внимательной работе с README и документацией они регулярно всплывают.

В целом GitLab Markdown действительно близок к GFM. Большинство базовых элементов — заголовки, списки, ссылки, кодовые блоки — работают ожидаемо. Но есть нюансы, которые важно учитывать.

Более строгая интерпретация структуры

GitLab обычно строже относится к структуре документа. Там, где GitHub «догадывается», GitLab чаще требует явной корректности.

Например, вложенные списки:

- Установка
  - Linux
  - macOS

Если отступы оформлены неаккуратно, GitHub может всё равно показать вложенность корректно. GitLab же в таком случае может «расплющить» список и потерять иерархию.

Хорошее правило для GitLab: 👉 если вы сомневаетесь в отступах — значит, их нужно поправить.

Расширения и «умные» возможности

GitLab поддерживает многие возможности, похожие на GFM, но не всегда полностью и не одинаково. Например:

  • автоматические ссылки и упоминания работают иначе;
  • некоторые элементы отображаются менее «богато»;
  • HTML-вставки чаще ограничиваются по соображениям безопасности.

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

Как это проявляется на практике

На практике различия обычно выглядят как мелкие визуальные расхождения:

  • список чуть менее аккуратен;
  • таблица выглядит строже;
  • блоки кажутся «плотнее»;
  • часть форматирования не срабатывает.

Документ при этом остаётся читаемым и рабочим. Но если вы привыкли к внешнему виду README в GitHub, GitLab может показаться более «сухим».

Именно поэтому важно помнить главное правило: 👉 не стоит рассчитывать, что всё, что красиво выглядит в GitHub, автоматически будет выглядеть так же в GitLab.

Практический вывод

Если Markdown-документ корректно выглядит в GitLab, он почти всегда будет нормально выглядеть и в GitHub. Обратное верно не всегда.

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

GitLab в этом смысле выступает как «строгий проверяющий»: если он принял разметку — значит структура действительно аккуратная.

Различия рендеринга: на что обращать внимание

Есть несколько зон, где различия проявляются чаще всего.

Списки и отступы

GitLab обычно строже относится к отступам. Там, где GitHub «прощает» неточность, GitLab может сломать вложенность. Хорошее правило: 👉 если список выглядит аккуратно в сыром Markdown — он почти всегда корректно отрендерится везде.

Таблицы

GitHub обрабатывает таблицы максимально дружелюбно. GitLab тоже их поддерживает, но иногда требует более аккуратного выравнивания. Если таблица выглядит сомнительно в исходном виде — при рендере это почти гарантированно проявится.

HTML внутри Markdown

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

Частые неожиданности

Даже опытные разработчики регулярно сталкиваются с сюрпризами при работе с Markdown в GitHub и GitLab.

Самые распространённые из них:

  • Markdown выглядит идеально локально, но «плывёт» в репозитории;
  • вложенные списки отображаются по-разному;
  • таблицы выглядят аккуратно только на одной платформе;
  • HTML работает в GitHub, но игнорируется в GitLab;
  • якоря к заголовкам ведут не туда, куда ожидалось.

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

Как писать Markdown, который работает везде

Есть несколько практических принципов, которые сильно снижают количество проблем.

  • придерживайтесь базового синтаксиса Markdown;
  • избегайте сложных HTML-вставок;
  • проверяйте вложенность списков и отступы;
  • не злоупотребляйте нестандартными расширениями;
  • смотрите на исходный Markdown, а не только на рендер.

Хорошее правило звучит так: 👉 если текст читаем и понятен без рендера — он почти всегда корректно отобразится в любой платформе.

Markdown как проверка качества документа

Различия между GitHub и GitLab часто воспринимают как проблему. Но на практике они выполняют полезную функцию: подсвечивают слабые места структуры.

Если документ разваливается при смене платформы, это почти всегда сигнал, что:

  • структура слишком хрупкая;
  • форматирование компенсирует слабый текст;
  • логика документа неочевидна.

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

Наиболее частые вопросы

  • Нужно ли писать отдельный Markdown для GitHub и GitLab?
    Нет. В большинстве случаев достаточно аккуратного базового Markdown.
  • Стоит ли использовать расширения GitHub Flavored Markdown?
    Можно, но осознанно. Особенно в README, который могут читать и в других средах.
  • Почему локальный просмотр отличается от GitHub?
    Потому что редакторы используют свои движки рендеринга, которые не всегда совпадают с платформами.

Итоги

В этом лонгриде вы разобрались:

  • как GitHub и GitLab рендерят Markdown;
  • почему один и тот же файл может выглядеть по-разному;
  • где чаще всего возникают неожиданности;
  • как писать Markdown, устойчивый к платформенным различиям.

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

В следующем лонгриде мы разберём расширения и диалекты Markdown: чем они отличаются, где уместны и когда лучше остаться в рамках базового синтаксиса.

На следующий урок