Форматы файлов
Что такое Markdown? Синтаксис, CommonMark и GFM
Markdown - облегченный язык разметки, который с помощью нескольких символов добавляет в простой текст заголовки, списки и ссылки. Рассказываем о его истории, стандартах и о том, что сохраняется при превращении файлов MD в Word или PDF.
Автор: Hemen Dönüştür Editör EkibiОпубликовано: 7 мин чтения
Вспомните README программного проекта, списки с заголовками в приложении для заметок или слова, которые вы выделяете звездочками в мессенджере. За всем этим стоит одна идея: Markdown. Markdown - облегченный язык разметки, позволяющий задавать заголовки, списки, ссылки и таблицы, добавляя в простой текст несколько простых символов. Файл остается читаемым в любом текстовом редакторе, но при необходимости его можно превратить в аккуратную HTML-страницу, документ Word или PDF. В этой статье расскажем, как появился Markdown, разберем его основной синтаксис, различия между CommonMark и GitHub Flavored Markdown и то, на что обращать внимание при конвертации файлов MD.
Что такое Markdown?
Markdown - это одновременно набор соглашений о написании текста и общее название инструментов, которые превращают написанный по ним текст в HTML. Файлы обычно сохраняются с расширением .md или .markdown. По словам создателя, Джона Грубера, главная цель дизайна - читаемость: документ Markdown должен быть пригоден к публикации как есть, в виде простого текста, и не выглядеть размеченным тегами или инструкциями форматирования. Там, где HTML требует <strong>важно</strong>, Markdown использует **важно**, и даже исходный вариант читается естественно.
Краткая история
Джон Грубер создал Markdown в 2004 году, а Аарон Шварц помогал ему, обсуждая и проверяя идеи. Синтаксис опирался на соглашения из текстовой электронной почты (звездочки для выделения, дефисы для списков) и на более ранние языки разметки, такие как setext и Textile. Версия 1.0.1 скрипта Markdown.pl на Perl, который Грубер опубликовал на своем сайте Daring Fireball, датирована 17 декабря 2004 года.
Однако описание Грубера объясняло формат на примерах и не было формальной спецификацией. Неоднозначные случаи (вложенные списки, блоки кода с отступами, смешивание с HTML) приводили к тому, что каждая реализация принимала собственные решения, и один и тот же текст стал давать разный результат в разных инструментах. Последовали два крупных ответа:
- CommonMark (2014): спецификация под руководством Джона Макфарлейна, которая однозначно определяет Markdown и делает его проверяемым с помощью сотен примеров. Первые версии появились осенью 2014 года; текущая версия 0.31.2 датирована 28 января 2024 года. Версия 1.0 спецификации пока не объявлена.
- GitHub Flavored Markdown (GFM, 2017): формальная спецификация GitHub, построенная поверх CommonMark. Она добавляет такие расширения, как таблицы, списки задач, зачеркивание, расширенные автоссылки, а также, ради безопасности, фильтрацию некоторых HTML-тегов. Последняя опубликованная спецификация 0.29-gfm датирована 6 апреля 2019 года.
Markdown получил признание и в инфраструктуре интернета: RFC 7763, опубликованный в марте 2016 года, зарегистрировал медиатип (MIME-тип) text/markdown с необязательным параметром variant, указывающим, какой вариант Markdown имел в виду автор.
Основные варианты Markdown
Помимо CommonMark и GFM существуют и другие распространенные варианты. RFC 7764, опубликованный вместе с RFC 7763, зарегистрировал некоторые из них и дал рекомендации по использованию:
- Markdown Extra: одно из ранних расширений, добавившее сноски, списки определений и таблицы.
- MultiMarkdown: вариант для академических текстов с метаданными, цитированием и перекрестными ссылками.
- Pandoc Markdown: диалект конвертера Pandoc с множеством расширений для написания книг и статей.
Практическое правило: если в документе только заголовки, списки, ссылки, код и простые таблицы, почти везде он будет выглядеть одинаково. Если вы используете сноски, списки определений или особые типы блоков, проверьте, какой вариант поддерживает целевая среда.
Основной синтаксис
Ту часть Markdown, которая нужна каждый день, можно освоить за несколько минут:
# Заголовок первого уровня
## Заголовок второго уровня
В этом абзаце есть **полужирный**, *курсив* и `код`.
- Маркированный список
- Второй пункт
- Вложенный подпункт
1. Нумерованный список
2. Второй шаг
[Текст ссылки](https://example.com)
> Цитата
```
Многострочный блок кода
```Таблицы и списки задач, добавленные GFM, выглядят так:
| Формат | Расширение |
|--------|------------|
| Markdown | .md |
| Простой текст | .txt |
- [x] Написать черновик
- [ ] Проверить егоАбзацы разделяются пустыми строками. Одиночный перевод строки в большинстве реализаций считается частью того же абзаца; чтобы принудительно перенести строку, закончите ее двумя пробелами. Внутри Markdown можно писать и HTML напрямую. CommonMark это допускает, хотя среды вроде GFM блокируют некоторые теги в целях безопасности.
Где используется Markdown?
- Разработка программ: README, журналы изменений и руководства для участников, а также задачи (issues) и комментарии к ревью кода на платформах вроде GitHub и GitLab.
- Техническая документация: генераторы статических сайтов, которые собирают сайты из файлов Markdown.
- Заметки: многие приложения для заметок хранят или экспортируют заметки в Markdown.
- Чаты и сообщества: платформы вроде Reddit и Discord используют варианты Markdown.
- Тексты и издательское дело: получение HTML, PDF, DOCX и EPUB из одного исходника Markdown с помощью инструментов вроде Pandoc.
- Инструменты ИИ: чат-ассистенты на основе ИИ часто оформляют ответы в Markdown.
Сильные и слабые стороны
| Сильные стороны | Слабые стороны |
|---|---|
| Читается даже в исходном виде | Варианты ведут себя по-разному |
| Простой текст: компактный, переносимый, удобный для контроля версий | Нет шрифтов, цветов и верстки страниц |
| Легко конвертируется в HTML, PDF и Word | Нет сложных таблиц (объединенных ячеек) |
| Осваивается за несколько минут | Изображения хранятся в отдельных файлах |
| Не привязан ни к какой программе | Ошибки в пробелах и отступах меняют результат |
Какие программы открывают Markdown?
Поскольку Markdown - это простой текст, он открывается в любом текстовом редакторе, включая Блокнот и TextEdit. Для просмотра с оформлением можно использовать встроенный предпросмотр Markdown в Visual Studio Code или специальные редакторы вроде Obsidian и Typora. GitHub и GitLab автоматически отображают файлы .md в репозиториях. А вот Word не открывает Markdown как форматированный текст, поэтому файл сначала нужно конвертировать.
Частые проблемы и их решение
Список или заголовок не отображается
CommonMark требует пробела после маркера заголовка: ## Заголовок, а не ##Заголовок. Списку, который идет после абзаца, часто тоже нужна пустая строка перед ним, чтобы он отобразился правильно.
Строки сливаются
Одиночный перевод строки не разделяет абзац. Оставьте пустую строку для нового абзаца или закончите строку двумя пробелами, чтобы перенести ее внутри абзаца.
Таблица работает на одной платформе, но не работает на другой
Таблицы не входят ни в исходный Markdown Грубера, ни в ядро CommonMark; они появились в расширениях вроде GFM. Проверьте, какой вариант поддерживает целевая платформа.
Абзац, начинающийся с числа, превращается в нумерованный список
Строка вроде «2024. Год выдался насыщенным» начинается с цифр и точки, поэтому может быть разобрана как список. Чтобы этого избежать, экранируйте точку обратной косой чертой (2024\.).
Советы по конвертации файлов Markdown
В нашем конвертере файлы Markdown загружаются на наш сервер и удаляются в течение 30 минут. Для чтения мы используем библиотеку Markdig с CommonMark и расширениями в стиле GitHub (таблицы, списки задач, сноски, автоссылки).
- Markdown в PDF и Markdown в Word сохраняют заголовки, списки, блоки кода, цитаты и таблицы с границами. Флажки списков задач превращаются в символы ☑ и ☐, чтобы оставаться видимыми в Word и PDF. По умолчанию текст набирается шрифтом с засечками размером 12 пт, а блоки кода моноширинным шрифтом.
- Markdown в HTML превращает README в самодостаточную веб-страницу с объявленной кодировкой символов.
- В обратную сторону Word в Markdown, HTML в Markdown и PDF в Markdown создают Markdown, совместимый с GitHub: заголовки, полужирный и курсивный текст, списки, таблицы, ссылки, блоки кода и цитаты сохраняются; шрифты, цвета и верстка страниц отбрасываются. В таблицах без строки заголовка первая строка становится заголовком, потому что таблицам GFM он обязателен. Обычные абзацы, начинающиеся с числа, например «1. Пункт», экранируются, чтобы случайно не превратиться в списки. Файл сохраняется в UTF-8 без BOM.
Часто задаваемые вопросы
Как открыть файл MD?
Его откроет любой текстовый редактор. Чтобы увидеть его с оформлением, используйте предпросмотр в Visual Studio Code или редактор Markdown; если хотите читать его в Word, конвертируйте в DOCX.
Чем CommonMark отличается от GitHub Flavored Markdown?
CommonMark задает основной синтаксис Markdown точными правилами. GFM - надмножество, которое добавляет поверх CommonMark расширения: таблицы, списки задач, зачеркивание и расширенные автоссылки.
Можно ли делать таблицы в Markdown?
Да, с расширениями вроде GFM можно писать простые таблицы с помощью вертикальных черт и дефисов. Для сложных структур, например объединенных ячеек, используйте HTML-таблицу или подготовьте документ в Word.
Чем Markdown отличается от HTML?
Markdown - более простой формат для письма, рассчитанный на превращение в HTML. Он не может выразить все, что умеет HTML, зато его исходный вид гораздо читабельнее. При необходимости внутри Markdown можно писать HTML.
Есть ли у Markdown официальный стандарт?
Исходное описание Грубера не является формальной спецификацией. Наиболее признанное точное определение сегодня дает CommonMark, а медиатип text/markdown зарегистрирован в RFC 7763 в марте 2016 года.
Источники
- Джон Грубер, Daring Fireball: Markdown
- CommonMark Spec (история версий)
- GitHub Flavored Markdown Spec
- IETF RFC 7763: The text/markdown Media Type (март 2016 года)
- IETF RFC 7764: Guidance on Markdown
- Википедия: Markdown (история, вторичный источник)
- Markdig: CommonMark-совместимый обработчик Markdown для .NET
