Зачем писать в Markdown
Markdown — лёгкий язык разметки, использующий простые символы для обозначения форматирования. Пишущему не нужно трогать мышь, он сосредоточен на содержании, а форматирование генерируется автоматически.
Преимущества:
- Чистый текст, открывается в любом редакторе
- Дружелюбен к контролю версий (Git умеет делать diff)
- Конвертируется в HTML, PDF, Word и другие форматы
- Низкий порог обучения, освоение за 10 минут
Базовый синтаксис
Заголовки
# Заголовок уровня 1
## Заголовок уровня 2
### Заголовок уровня 3
#### Заголовок уровня 4
Рекомендуется один заголовок уровня 1 на статью.
Абзацы
Пустые строки разделяют абзацы. Содержимое без пустой строки считается одним абзацем.
Выделение
**жирный**
*курсив*
~~зачёркнутый~~
Списки
Неупорядоченные:
- пункт
- пункт
- подпункт (с отступом)
Упорядоченные:
1. Первый пункт
2. Второй пункт
Ссылки и изображения
[текст ссылки](https://example.com)
Код
В строке: код
Блок кода:
```javascript
const x = 1;
### Цитата
текст цитаты вторая строка
### Горизонтальная линия
## Расширенный синтаксис
### Таблицы
| Имя | Возраст |
|---|---|
| Tom | 25 |
### Список задач
- Выполнено
- Не выполнено
### Сноски
Текст[^1]
[^1]: Пояснение сноски
### Зачёркивание
зачёркнутый
### Автоссылки
URL автоматически превращается в ссылку.
## Техники письма
### Чёткая иерархия заголовков
- Заголовок уровня 1: название статьи
- Заголовок уровня 2: основные разделы
- Заголовок уровня 3: подразделы
- Не пропускайте уровни (с уровня 1 сразу на уровень 3)
### Краткие абзацы
- Один абзац — одна мысль
- Абзацы не слишком длинные (3-5 строк оптимально)
- Используйте списки вместо длинных абзацев
### Грамотное использование списков
Параллельное содержимое оформляйте списками, это яснее абзацев:
- Шаги — упорядоченные списки
- Параллельные пункты — неупорядоченные списки
- Сравнения — таблицы
### Указывайте язык в блоках кода
Указывайте язык в блоке кода для подсветки синтаксиса:
Добавляйте описания к изображениям
Описание в  важно:
- Показывается, когда изображение не загрузилось
- Программы чтения с экрана зачитывают описание для слабовидящих
- Полезно для SEO
Понятные ссылки
- Текст ссылки описывает назначение, не используйте «нажмите здесь»
- Внешние ссылки — полный URL
- Внутренние ссылки — относительный путь
Организация документов
Содержание в начале
Длинные документы начинайте с содержания, со ссылками на разделы. Удобно для навигации.
Разделяйте разделы заголовками
Разделяйте разделы заголовками, а не горизонтальными линиями. Заголовки имеют иерархию, линии — нет.
Разделяйте код и текст
Оставляйте пустую строку до и после блоков кода, отделяя их от основного текста. Чтение становится яснее.
Размещайте изображения в нужном месте
Изображения должны стоять рядом с соответствующим текстом, а не группироваться в конце. Читатель при последовательном чтении увидит изображение вовремя.
Выбор редактора
VS Code
- Бесплатный и мощный
- Установите плагины Markdown (например, Markdown All in One)
- Предпросмотр в реальном времени
- Подходит разработчикам
Typora
- WYSIWYG (что видите, то и получаете)
- Без окна предпросмотра, прямое редактирование готового результата
- Платный, но недорогой
- Подходит для сосредоточенной работы
Obsidian
- Локальная база знаний
- Двусторонние ссылки
- Богат плагинами
- Подходит для заметок и управления знаниями
Онлайн-редакторы
- StackEdit: онлайн-редактор Markdown
- Цзяньшу: платформа для письма на китайском
- Подходит для временной работы
Markdown в HTML
После написания в Markdown для показа на веб-странице нужно преобразовать в HTML. Используйте инструмент Markdown в HTML для мгновенного преобразования.
Частые ошибки
Нет пробела после заголовка
#заголовок не распознаётся, нужно # заголовок (пробел после #).
Неверный отступ списка
Подсписки должны иметь отступ 2 или 4 пробела (зависит от парсера). При неверном отступе подсписок не отображается.
Незакрытый блок кода
### Неэкранированные спецсимволы
Чтобы показать символы вроде * и #, добавьте \ перед ними: \* показывает *.
### Ошибка синтаксиса таблицы
В таблице нужна строка-разделитель заголовка (| --- |). Без неё таблица не распознаётся.
### Несогласованные скобки ссылки
`[ссылка](url` без закрывающей скобки — ссылка не распознаётся.
## Лучшие практики
### Один документ — одна тема
Статья должна раскрывать одну тему. Несколько тем разбивайте на несколько статей и связывайте ссылками.
### Сначала содержание, потом форматирование
Сначала пишите чистый текст, затем добавляйте разметку Markdown. Не правьте формат на ходу, это сбивает ход мысли.
### Единый стиль
Команда писателей должна выработать единый стиль:
- Сколько уровней заголовков использовать
- Списки через - или *
- Указание языка в блоках кода
- Максимум уровней вложенности списков
### Сохраняйте исходный файл
Markdown — исходный файл, HTML/PDF — результат. Сохраняйте Markdown для удобства правок, каждый раз перегенерируя выходные форматы.
## Итоги
Суть письма в Markdown: чёткая иерархия заголовков, краткие абзацы, грамотное использование списков, указание языка в коде, описания к изображениям. Выберите подходящий редактор, стандартизируйте стиль, сохраняйте исходный файл. Для показа используйте [инструмент Markdown в HTML от DocsAll](/convert-tools/markdown-to-html), работающий в браузере.