Що таке Markdown? Синтаксис, CommonMark і GFM

Згадайте 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)
![Опис зображення](image.png)
> Цитата
```
Багаторядковий блок коду
```

Таблиці та списки завдань, додані 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.

Переваги й недоліки

Якими програмами відкрити 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 року.

Джерела

• John Gruber, 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