[disсrete]
== Заголовок второго уровняСтайлгайд по работе с AsciiDoc
AsciiDoc — это формат текстового документа для написания заметок, документации, статей, книг, электронных книг, слайд-шоу, веб-страниц, страниц руководства и блогов. Файлы AsciiDoc можно перевести во многие форматы, включая HTML, PDF, EPUB, справочную страницу.
В статье рассмотрены:
Общие требования к работе в Asciidoc
Лучшие практики
Заголовки
Заголовки должны идти последовательно — не ставьте заголовки третьего уровня без заголовков второго.
= — заголовок первого уровня (один на весь adoc-файл), ставится в начале страницы;
== — заголовок второго уровня;
=== — заголовок третьего уровня.
Заголовок второго уровня автоматически создает разделитель. Если вам нужно убрать его — добавьте перед заголовком атрибут [discrete]:
Изображения
Картинки чувствительны к регистру и указанному формату — будьте внимательны и отслеживайте ошибки в вашей среде разработки. Обычно в них встроен механизм, который помогает достраивать ссылки, в том числе и на изображения.
Управляйте масштабом ваших изображений через [width=%]. Например, 20%:
Управляйте расположением изображений, сославшись через image:: (с двумя двоеточиями для принудительного переноса) и используя атрибуты center (центрировать), left (левый край), right (правый край). Например, по центру:
Списки
Нумерованные списки задаются точками .:
-
Первый номер списка, первый уровень вложенности
-
Второй номер списка, первый уровень вложенности
-
Первый уровень списка, первый уровень вложенности
-
Второй уровень списка, второй уровень вложенности
-
Третий уровень списка, третий уровень вложенности
-
-
Маркированные списки задаются звездочками *:
-
На первом уровне вложенности
-
На первом уровне вложенности
-
Первый уровень вложенности
-
Второй уровень вложенности
-
Третий уровень вложенности
-
-
Чтобы соединить списки с блоком контента используйте +:
-
Первый уровень
Абзац на том же уровне, что и список первого уровня
-
Второй уровень
Абзац на том же уровне, что и список второго уровня
-
Аналогично для маркированного списка.
Ссылки
Для внутренних ссылок на файлы (xref) и на изображения (image) используется относительный путь. Для ссылок из сети интернет (link) используется URL.
В квадратных скобках [] в конце внутренних и внешних ссылок можно задать текст, отображаемой вместо текста (alt-text) по умолчанию (имя заголовка adoc-файла или сама ссылка).
Формулы
При составлении формул пользуйтесь сайтом https://asciimath.org/.
Используйте бэкслэши \, чтобы избавиться от зарезервированных слов. Например, \$le\$ создает знак ≤, используйте \ "l\e" если хотите получить неизмененный результат. Список зарезервированных слов смотрите здесь.
Для создания пробелов в формулах используйте пробел в кавычках " " или бэкслэш \ (обратная косая черта).
Вы можете создавать формулы как через stem:[], так и через конструкцию:
\$\$
Примечания
Примечания (admonitions) задаются заглавными буквами в квадратных скобках. Идущий после примечания абзац будет автоматически выбран как содержимое примечания. Если в примечание необходимо добавить несколько абзацев — оберните содержимое в четыре знака равенства ====:
| Содержимое примечания в один абзац. |
|
Содержимое примечания первого абзаца. Содержимое примечания второго абзаца. |
Доступны следующие примечания:
| Текст Note (примечание). |
| Текст Tip (совет). |
| Текст Important (важно). |
| Текст Caution (внимание). |
| Текст Warning (предупреждение). |
Код
Укажите код используя конструкцию:
код
Дополнительно можете указать язык обработки блока кода — блок будет отображать синтаксис аналогично заданному языку. Например, python:
name = input('What is your name?')
print('Hey! your name is' + name)Якоря
Якорь ссылается на конкретное место adoc-файла и задается в квадратных скобках с использованием решетки #. Например, [#anchor_1]. Учитываются правила:
-
Якорь не могут иметь одинаковых названий в одном adoc-файле.
-
Якорь может быть выставлен в любом месте adoc-файла с нового абзаца.
-
Якорь не будет работать внутри форматируемых блоков по типу stem:[] или блоков кода, имеющих собственный синтаксис:
[#якорь] == Название раздела на который хотим сослаться
Чтобы сослаться на якорь, добавьте его идентификатор в конце ссылки xref, но до квадратных скобок []. Например:
xref:адок-файл_1#anchor_1[] #сослались на якорь [#anchor_1] в файле адок-файл_1.adoc.Таблицы
Границы таблицы задаются с помощью |===, а для составления ячеек используются |. Перед таблицей можно использовать квадратные скобки [] для задания настроек:
ячейка 1 |
ячейка 2 |
ячейка 3 |
ячейка 4 |
Можно не использовать квадратные скобки [], тогда таблица построится по умолчанию:
ячейка 1 |
ячейка 2 |
ячейка 3 |
ячейка 4 |
Выделение заголовка полужирным может задаваться как через [%header], так и через [options="header"]:
| ячейка 1 | ячейка 2 |
|---|---|
ячейка 3 |
ячейка 4 |
| ячейка 1 | ячейка 2 |
|---|---|
ячейка 3 |
ячейка 4 |
Управление цветом
Изменение цвета текста осуществляется через встроенные роли [.color], где color — желаемый цвет, например [.aqua] создаст Аквамариновый цвет. Доступны следующие цвета для стандартных ролей:
[.aqua] |
Аквамариновый |
[.black] |
Черный |
[.blue] |
Синий |
[.fuchsia] |
Фуксия |
[.gray] |
Серый |
[.green] |
Зеленый |
[.lime] |
Лайм |
[.maroon] |
Темно-бордовый |
[.navy] |
Темно-синий |
[.olive] |
Оливковый |
[.purple] |
Фиолетовый |
[.red] |
Красный |
[.silver] |
Серебряный |
[.teal] |
Сине-зеленый |
[.white] |
Белый |
[.yellow] |
Желтый |