Полное руководство по Markdown

Markdown повсюду. Это формат записей по умолчанию на GitHub, основа большинства генераторов статических сайтов, родной язык таких инструментов, как Obsidian и Notion, и формат, к которому разработчики обращаются при написании README, документации и технических заметок. Несмотря на повсеместность, многие авторы и разработчики осваивают только основы — жирный шрифт, курсив и несколько уровней заголовков — и упускают возможности, делающие Markdown по-настоящему мощным для структурированного письма.

Вы можете писать и предварительно просматривать Markdown мгновенно с помощью редактора Markdown BrowseryTools — бесплатно, без регистрации, всё остаётся в браузере.

Кто создал Markdown и зачем

Markdown был создан Джоном Грубером в сотрудничестве с Аароном Шварцем и выпущен в 2004 году. Заявленная цель Грубера — создать формат написания обычного текста, который читаем как есть — до любого рендеринга — и который чисто конвертируется в валидный HTML. Название — игра слов на «язык разметки» (HTML — HyperText Markup Language), переворачивающая концепцию: вместо добавления синтаксиса для управления форматированием Markdown использует пунктуационные привычки, которые люди уже выработали в электронной почте с обычным текстом.

Мотивация была практической. HTML многословен и отвлекает при встроенном написании. Предложение вроде <p>This is <strong>important</strong> text.</p> требует значительных умственных затрат по сравнению с This is **important** text. Грубер хотел, чтобы блогеры и авторы сосредоточились на словах, а не на тегах. Оригинальная спецификация Markdown была Perl-скриптом, конвертирующим обычные текстовые файлы Markdown в HTML.

Базовый синтаксис

Основной синтаксис Markdown покрывает всё, что нужно большинству авторов для структурированных документов.

Заголовки

Используйте символы решётки для создания заголовков. Одна решётка для H1, две для H2, до шести для H6. Большинство стайл-гайдов рекомендуют только один H1 на документ (обычно заголовок) и использование H2–H4 для иерархии содержимого.

# Заголовок 1
## Заголовок 2
### Заголовок 3
#### Заголовок 4

Акцент и выделение

*курсив* или _курсив_
**жирный** или __жирный__
***жирный и курсив***
~~зачёркнутый~~

Ссылки и изображения

[Текст ссылки](https://example.com)
[Ссылка с заголовком](https://example.com "Заголовок страницы")
![Альтернативный текст](image.png)
![Альтернативный текст](image.png "Заголовок изображения")

Списки

Маркированные списки используют дефисы, звёздочки или знаки плюс. Нумерованные списки используют цифры с точками. Отступы (2 или 4 пробела) создают вложенные списки.

- Элемент маркированного списка
- Ещё один элемент
  - Вложенный элемент

1. Первый
2. Второй
3. Третий

Код

Встроенный код использует одиночные обратные кавычки. Блоки кода с ограждением используют тройные обратные кавычки с необязательным идентификатором языка для подсветки синтаксиса.

Используйте `console.log()` для отладки.

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

Блочные цитаты

> Это блочная цитата.
> Она может занимать несколько строк.
>
> > Вложенные блочные цитаты тоже работают.

Горизонтальные разделители

Три или более дефисов, звёздочки или подчёркивания на отдельной строке создают горизонтальный разделитель. --- — самое распространённое соглашение.

Расширенный синтаксис

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

Таблицы

| Столбец 1 | Столбец 2 | Столбец 3 |
|-----------|:---------:|----------:|
| Слева     | По центру |  Справа   |
| выровнен  | выровнен  | выровнен  |

Положение двоеточия в строке-разделителе управляет выравниванием: слева (по умолчанию), по центру (двоеточия с обеих сторон) или справа (двоеточие справа).

Списки задач

- [x] Написать первый черновик
- [x] Рецензирование
- [ ] Финальная правка
- [ ] Публикация

Сноски

Вот утверждение, требующее ссылки.[^1]

[^1]: Здесь источник или пояснение.

Разновидности Markdown: CommonMark, GFM и MDX

Исходная спецификация Markdown содержала неоднозначности — места, где процессоры принимали разные решения в граничных случаях. Это привело к несовместимым реализациям в разных инструментах. Для устранения этого появилось несколько инициатив по стандартизации.

• CommonMark — строгая спецификация, устраняющая каждую неоднозначность исходной спецификации Markdown с формальным набором тестов. Принята Discourse, Reddit, Stack Overflow и многими другими. Наиболее интероперабельный вариант.
• GitHub Flavored Markdown (GFM) — расширение CommonMark от GitHub, добавляющее таблицы, списки задач, зачёркивание, автоссылки и буквальные URL. Если вы пишете README-файлы или комментарии на GitHub, вы используете GFM.
• MDX — Markdown, расширенный поддержкой JSX-компонентов, широко применяемый в сайтах документации на основе React (Next.js docs, Docusaurus, Astro). Позволяет импортировать и встраивать React-компоненты непосредственно в Markdown-файлы.
• MultiMarkdown / Pandoc Markdown — функционально богатые расширения для академического письма с поддержкой цитат, математических уравнений (LaTeX) и сложного форматирования таблиц.

Где используется Markdown

• GitHub и GitLab — README-файлы, задачи, pull request-ы, вики и комментарии — всё рендерится из Markdown
• Notion — поддерживает импорт/экспорт Markdown и подмножество горячих клавиш Markdown для встроенного форматирования
• Obsidian — приложение для управления знаниями, построенное целиком на Markdown-файлах с расширениями wikilink
• Генераторы статических сайтов — Jekyll, Hugo, Gatsby, Astro и Next.js используют Markdown или MDX как формат контента по умолчанию
• Платформы документации — ReadTheDocs, GitBook и Docusaurus построены на основе Markdown
• Платформы чата — Slack, Discord и Teams поддерживают подмножества Markdown для форматирования сообщений
• Почтовые клиенты — некоторые клиенты (Superhuman, HEY) поддерживают ввод Markdown

Markdown против редакторов форматированного текста

Редакторы форматированного текста (WYSIWYG — «что видишь, то и получишь»), такие как Google Docs, Microsoft Word или встроенный редактор Contentful, показывают форматированный вывод в процессе набора. Markdown показывает сырой исходник. Компромиссы реальны.

• Преимущества Markdown — текстовые файлы, работают в любом редакторе, поддерживают контроль версий через git, нет привязки к конкретному поставщику, быстрый рабочий процесс только с клавиатурой
• Преимущества форматированного текста — сразу наглядно, не нужно учить синтаксис, удобнее для нетехнических авторов, лучше для сложного форматирования (сноски, комментарии, отслеживание изменений)

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

Распространённые ошибки в Markdown

• Пропущенные пустые строки — большинство блочных элементов (заголовки, списки, блоки кода) требуют пустой строки до и после себя для корректного рендеринга
• Пробелы после символов решётки — ##Заголовок без пробела после решёток — не заголовок в большинстве процессоров
• Непоследовательные маркеры списков — смешение - и * в одном списке может давать неожиданные результаты в некоторых процессорах
• Забытое экранирование специальных символов — звёздочки, подчёркивания и обратные кавычки внутри текста требуют экранирования обратным слэшем, если должны рендериться буквально
• Предположение об универсальности расширенного синтаксиса — таблицы и списки задач являются функциями GFM, не поддерживаемыми всеми процессорами; проверяйте целевую среду

Редактор Markdown BrowseryTools предоставляет живой предварительный просмотр, чтобы вы могли замечать проблемы рендеринга сразу в процессе написания, без копирования текста в другой инструмент. Вставьте Markdown и смотрите рендеренный HTML бок о бок.