Форматы: AsciiDoc
24.11.2024
AsciiDoc — облегчённый язык разметки, ориентирован, в первую очередь, на технические тексты. Формат имеет очень широкие возможности и подробную документацию. Переписывать документацию не имеет смысла, поэтому далее будут отмечены только некоторые примечательные особенности формата.
Ссылки
- Asciidoctor — инструмент для конвертации AsciiDoc в другие форматы
- Awesome AsciiDoc
- AsciiDoc Syntax Quick Reference
- Compare AsciiDoc to Markdown
Блоки
Документ AsciiDoc состоит из блоков. Блоки бывают разных видов. Есть возможность указывать заголовок блока, идентификатор блока, стиль и атрибуты блока.
Самый простой блок — абзац. Такие блоки разделяются пустыми строками.
Первый абзац.
Второй абзац.
Некоторые типы блоков начинаются и заканчиваются специальной для каждого типа блока последовательностью символов, например:
Text in your document.
****
This is content in a sidebar block.
This is more content in the sidebar block.
****
Заголовок блока — строка перед блоком, которая начинается с точки:
.This is the title of a sidebar block
****
This is the content of the sidebar block.
****
Атрибуты блока задаются в квадратных скобках перед блоком:
.Specify GitLab CI stages
[source,yaml]
----
image: node:16-buster
stages: [ init, verify, deploy ]
----
Доступны функции: переопределение заголовка блока и автоматическая нумерация (например, «Пример 1», «Пример 2» и т. д.).
.Block Title
[caption="Example {counter:my-example-number:A}: "]
====
Block content
====
Идентификатор блока устанавливается в квадратных скобках с использованием символа #
:
[#the-id-of-this-block]
====
Content of delimited example block
====
Атрибуты
Формат имеет возможность установки аттрибутов как всему документу
= My Document
:imagesdir: ./images
:iconsdir: ./icons
:stylesdir: ./styles
:scriptsdir: ./js
так и отдельным элементам, как блочным
[#rules.prominent%incremental]
* Work hard
* Play hard
* Be happy
так и инлайновым
[#idname.rolename]*text with id and role*
Секции
Секции похожи на заголовки Markdown, но поддерживают больше возможностей.
= Document Title (Level 0)
== Level 1 Section Title
=== Level 2 Section Title
==== Level 3 Section Title
===== Level 4 Section Title
====== Level 5 Section Title
== Another Level 1 Section Title
В формате указан способ автоматического формирования идентификатора секции на основе заголовка секции. Например, по умолчанию для секции
== Wiley & Sons, Inc.
Будет сгенерирован идентификатор _wiley_sons_inc
. Присутствует возможность отключать автоматическую генерацию идентификаторов или задавать произвольные идентификаторы. Есть возможность автоматической нумерации секций.
Параграфы
Переводы строки внутри параграфа игнорируются при конвертации. Принудительный перевод строки можно сделать с помощью символа +
или с применением атрибутов блока.
Rubies are red, +
Topazes are blue.
[%hardbreaks]
Ruby is red.
Java is beige.
Некоторые параметры внешнего вида текста регулируются специальными атрибутами, которые называются ролями, они похожи классы CSS.
[.text-center]
This text is centered, so it must be important.
Макросы
Для особых случаев применяются макросы. Они бывают двух видов: блочные и инлайновые. Изображения и примечания реализованы через макросы. Блочный макрос начинается с названия, затем идут два символа :
, затем аргументы и список атрибутов.
Content in document.
image::sunset.jpg[]
Content in document
К изображению может быть добавлена подпись через заголовок блока или через атрибуты.
.A mountain sunset
[#img-sunset,link=https://www.flickr.com/photos/javh/5448336655]
image::sunset.jpg[Sunset,200,100]
Инлайновые макросы выглядят так же, только используется один символ :
, так выглядят примечания:
The hail-and-rainbow protocol can be initiated at five levels:
. doublefootnote:[The double hail-and-rainbow level makes my toes tingle.]
. tertiary
. supernumerary
. supermassive
. apocalyptic
A bold statement!footnote:disclaimer[Opinions are my own.]
Another outrageous statement.footnote:disclaimer[]
Списки
Вложенность маркированных и нумерованных списков определяется количеством символов разметки.
.Possible DefOps manual locations
* West wood maze
** Maze heart
*** Reflection pool
** Secret exit
* Untracked file in git repository
. Step 1
. Step 2
.. Step 2a
.. Step 2b
. Step 3
Поддерживаются различные способы нумерации нумерованных списков.
Таблицы
Кроме базового синтаксиса таблиц есть много других возможностей, включая вложенные таблицы и использование формата CSV.
[cols="1,1"]
|===
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 1, row 3
|Cell in column 2, row 3
|===
Цитаты
Автора цитаты можно указать через атрибуты блока.
.After landing the cloaked Klingon bird of prey in Golden Gate park:
[quote,Captain James T. Kirk,Star Trek IV: The Voyage Home]
Everybody remember where we parked.
Так же поддерживаются цитаты в стиле Markdown.
> I hold it that a little rebellion now and then is a good thing,
> and as necessary in the political world as storms in the physical.
> -- Thomas Jefferson, Papers of Thomas Jefferson: Volume 11
Итоги
Формат AsciiDoc значительно лучше проработан и стандартизован чем Markdown, для которого каждый парсер и организация добавляют свои расширения. Формат подходит для создания сложных документов: есть возможности кастомизации оглавления, вставки одного документа в другой и др. AsciiDoc может подойти для оцифровки значительной части литературы, его можно продуктивно использовать в текстологии.