Форматы: AsciiDoc

24.11.2024

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

Ссылки

Блоки

Документ 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 может подойти для оцифровки значительной части литературы, его можно продуктивно использовать в текстологии.

Последниее изменение: