AsciiDoc выбирают для больших документов: в нём есть оглавление, сквозные ссылки, включение файлов и атрибуты — то, чего не хватает в Markdown. Редактор показывает документ так, как его соберёт Asciidoctor.
Как работать
- Откройте песочницу AsciiDoc — там пример со всеми возможностями.
- Пишите слева — справа предпросмотр Asciidoctor.
- Скачайте: Файл → Скачать — AsciiDoc (.adoc) или страница HTML.
Возможности
- Оглавление (
:toc:), нумерация разделов, якоря и перекрёстные ссылки<<раздел>>. - Таблицы
|===с заголовками и объединением ячеек. - Предупреждения
NOTE:,TIP:,WARNING:,IMPORTANT:,CAUTION:. - Формулы
stem:[…]. - Диаграммы: блоки
[plantuml]и[mermaid]рисуются в предпросмотре.
Документ из нескольких файлов
Главное преимущество AsciiDoc — include::. В проекте можно собрать документ из частей:
= Постановка: оформление заказа
:toc:
include::parts/requirements.adoc[]
include::parts/integration.adoc[]Пути разрешаются от папки документа по дереву папок проекта; Ctrl+клик по include:: или xref: открывает файл.
Markdown ↔ AsciiDoc
- Файл → Преобразовать в → Markdown: включения раскрываются, предупреждения становятся
> [!NOTE], диаграммы — блоками```plantuml. - Из редактора Markdown — Преобразовать в → AsciiDoc: таблицы, предупреждения и диаграммы переводятся в синтаксис AsciiDoc, ссылки на файлы пересчитываются от папки, куда сохраняется результат.
Пример
= Требования к оформлению заказа
:toc:
NOTE: Пример документа.
== Функциональные требования
[cols="1,3,1", options="header"]
|===
| № | Требование | Приоритет
| Ф-1 | Клиент оформляет заказ из корзины | Высокий
|===
[plantuml]
----
@startuml
Клиент -> Магазин: оформить заказ
@enduml
----Вопросы и ответы
Что выбрать — Markdown или AsciiDoc? Markdown — для коротких документов и README; AsciiDoc — для больших документов, которые собираются из частей, с оглавлением и перекрёстными ссылками.
Работает ли include из песочницы? Нет: включаемые файлы берутся из проекта. В песочнице на месте включения будет предупреждение.