Markdown: пиши один раз, публикуй везде

Тебе нужно написать документацию. Или README. Или блог-пост. Или Slack-сообщение с форматированием.

HTML — перебор. Word-документы не работают везде. Простой текст не имеет форматирования.

Markdown находится в золотой середине. Простой синтаксис, читаемый как простой текст, конвертируется в HTML при необходимости.

Основы

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

**жирный** и *курсив*

- Буллет
- Другой пункт
  - Вложенный пункт

1. Нумерованный список
2. Второй пункт

[Текст ссылки](https://example.com)

![Альтернативный текст изображения](image.jpg)

Это большая часть того, что тебе нужно.

Форматирование кода

Встроенный код с обратными кавычками: console.log('hello')

Блоки кода с тройными обратными кавычками:

function hello() {
  return 'world';
}

Укажи язык после открывающих обратных кавычек для подсветки синтаксиса.

Таблицы

| Имя   | Роль       |
|-------|------------|
| Алиса | Разработчик  |
| Боб   | Дизайнер   |

Таблицы сложно печатать. У большинства редакторов есть шорткаты.

Цитаты

> Это цитата.
> Она может занимать несколько строк.

Используй для выносок, цитат или выделения важного текста.

Почему Markdown работает

Читаемый исходник. Даже без рендеринга Markdown легко читать. **жирный** очевидно жирный.

Переносимый. GitHub, Notion, Slack, Reddit, бесчисленные генераторы статических сайтов. Пиши один раз, вставляй везде.

Дружелюбен к контролю версий. Это простой текст. Git diff имеют смысл. Слияния работают.

Защищён от будущего. Никакого проприетарного формата. Твой контент доступен навсегда.

Различия во вкусах

GitHub Flavored Markdown (GFM) добавляет чекбоксы, таблицы и подсветку синтаксиса.

CommonMark — это усилия по стандартизации. Большинство платформ поддерживают его.

Некоторые платформы добавляют экстры: Obsidian имеет вики-ссылки, Notion имеет базы данных.

Для максимальной переносимости придерживайся базового синтаксиса.

Частые ошибки

Забываешь пустые строки. Абзацам нужны пустые строки между ними. Без них всё сливается вместе.

Пробелы после заголовков. #Заголовок не работает. # Заголовок работает. Заметь пробел.

Сломанные ссылки. Отсутствие https:// делает ссылки неработающими на некоторых платформах.

Изображения без альтернативного текста. ![](image.jpg) работает, но недоступно. Добавляй описания.

Советы по написанию

Используй заголовки для структуры. Читатели сканируют перед чтением.

Держи абзацы короткими. Пустое пространство помогает читаемости.

Предпросматривай перед публикацией. Разные рендереры обрабатывают крайние случаи по-разному.

---

Markdown убирает трение из написания. Изучи основы один раз, используй их везде. Простота — это фича.