Markdown — стандарт для документации рядом с кодом: README, ADR, постановки. Редактор показывает документ так, как его покажет GitHub, и дополнительно рисует диаграммы.
Как работать
- Откройте песочницу Markdown — там пример документа со всеми возможностями.
- Пишите слева — справа предпросмотр обновляется по мере ввода.
- Скачайте результат: Файл → Скачать — Markdown (.md) или страница HTML (.html).

Что поддерживается
- Заголовки, списки, таблицы, цитаты, код с подсветкой — по GitHub Flavored Markdown.
- Списки задач:
- [x] Согласовано,- [ ] Проверено. - Предупреждения как на GitHub:
> [!NOTE],[!TIP],[!IMPORTANT],[!WARNING],[!CAUTION]. - Сноски
[^1]и формулы$E = mc^2$,$$ … $$. - Диаграммы: блоки
```plantumlи```mermaidрисуются в предпросмотре.
Диаграммы в тексте
```mermaid
flowchart LR
Корзина --> Оформление --> Оплата
```
Mermaid удобен для простых блок-схем и графиков, PlantUML — для UML-диаграмм. Оба рисуются при просмотре, а в исходнике остаются кодом, который легко править.
Ссылки на файлы проекта
В проекте документы ссылаются на соседние файлы: [спецификация](../api/orders.yaml). Ctrl+клик по ссылке в коде или щелчок в предпросмотре открывает файл. Неверные пути видны в проверке документа, которой пользуются API и ИИ-агенты.
Другие форматы
- Word — «Markdown в Word».
- AsciiDoc — Файл → Преобразовать в → AsciiDoc (см. «Редактор AsciiDoc»).
Пример документа
# Оформление заказа
> [!NOTE]
> Требования согласованы с бизнесом 01.10.
| № | Требование | Приоритет |
|---|---|---|
| Ф-1 | Оформление из корзины | Высокий |
- [x] Согласовано
- [ ] Протестировано
```plantuml
@startuml
Клиент -> Магазин: оформить заказ
@enduml
```
Вопросы и ответы
Отличается ли предпросмотр от GitHub? Основной синтаксис совпадает с GitHub Flavored Markdown. Диаграммы PlantUML GitHub не рисует (только Mermaid), поэтому на GitHub такие блоки будут показаны кодом.
Можно ли вставить картинку? Да, ссылкой: . Загрузки картинок в документ нет — для схем используйте диаграммы в коде.
Как сделать оглавление? В Markdown оглавление пишется списком ссылок вручную. Если нужен автоматический — используйте AsciiDoc с :toc:.
