Клавиатура AsciiDoc онлайн: разметка документации

Разметка, на которую переходят, когда руководство перерастает Markdown.

Для работы инструмента нужен JavaScript. Включите его в настройках браузера и обновите страницу - описание и ответы ниже доступны и без него.

Предпросмотр

Предпросмотр примерный: он показывает смысл разметки, а не то, как её нарисует конкретное приложение. Шрифты, цвета и отступы везде свои, а часть возможностей зависит от версии.

0 симв.

Что пишет каждая кнопка

Действие	Синтаксис	Примечание
B	`bold`	Жирный - одна звёздочка
I	`_italic_`	Курсив
Mono	`monospace`	Моноширинный
Mark	`#highlight#`	Выделение маркером
Title	`= Document title`	Заголовок документа - один на файл
H2	`== Section`	Раздел
H3	`=== Subsection`	Подраздел
List	`* item`	Маркированный список
.	`. item`	Нумерованный список - точка, а не цифра
Code	`[source,js] ---- code ----`	Блок кода с языком
NOTE	`NOTE: text`	Примечание
TIP	`TIP: text`	Совет
WARNING	`WARNING: text`	Предупреждение
IMPORTANT	`IMPORTANT: text`	Важно
Link	`link:https://example.com[text]`	Ссылка - сначала адрес, текст в скобках
Image	`image::file.png[alt]`	Блок изображения
Table	`\|=== \| a \| b \|===`	Таблица

Для документов, а не для комментариев

Markdown придумывали для коротких текстов в вебе, и каждый проект, которому его стало мало, дописывал свои расширения. AsciiDoc сразу исходит из документа: заголовок, разделы, перекрёстные ссылки, предупреждения, включения файлов, подписи и атрибуты. Поэтому на нём пишут технические книги и длинные руководства.

Что даёт синтаксис

Заголовки - знаки равенства в начале строки: один для названия документа, больше для каждого уровня ниже. Жирный - одна звёздочка, курсив - подчёркивание. Язык блока кода пишется в атрибуте в квадратных скобках над блоком.

Предупреждения - одно слово в начале: NOTE, TIP, WARNING, IMPORTANT, CAUTION, и они читаются даже в терминале. Ссылки пишутся наоборот, чем в Markdown: сначала адрес, потом текст в квадратных скобках.

Как пользоваться

Начните с заголовка документа. Один знак равенства, один раз на файл, всё остальное вкладывается под него.
Вместо жирных предупреждений ставьте NOTE: и WARNING:. Они выводятся плашками и понятны даже в простом тексте.
Скопируйте текст в файл. Нажмите "Копировать всё" и вставьте в файл .adoc в репозитории.

Вопросы и ответы

AsciiDoc или Markdown для документации?

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