Конвертация документов в формате Asciidoc в формат хранения Confluence и публикация на сервер Confluence.
Программа имеет интерфейс CLI. Предназначена для конвертации одного документа в формате Asciidoc в формат хранения Confluence и публикации на сервер Confluence. При этом выполняется также загрузка изображений, используемых в статье.
Заголовок документа (заголовок первого уровня) используется в качестве названия страницы. Он же используется для поиска страницы в пространстве Confluence, если явно не указан её идентификатор.
Предусмотрено два режима публикации страницы: первичная публикация и обновление.
Первичная публикация предполагает, что на момент её выполнения в указанном пространстве не будет страницы с таким же названием, как у публикуемой. При публикации выполняется проверка, и, если она обнаружит, что страница с таким названием уже имеется, произойдёт отказ в публикации. Это позволяет предохранить от затирания другую страницу, с которой совпало название публикуемой.
Для первичной публикации обязательно нужно указать ключ пространства, в которое будет выполнена публикация, а также идентификатор родительской страницы.
При обновлении опубликованной ранее страницы происходит замещение контента существующей на Confluence страницы. При этом, в отличие от первичной публикации, отказ произойдёт, если не удастся найти в Confluence существующую страницу для обновления.
Страница для обновления ищется всегда по идентификатору в Confluence. Если утилита вызвана для обновления одной страницы, необходимо указать идентификатор в параметре вызова page-id. В режиме пакетного обновления идентификаторы должны присутствовать в файле со списком страниц. Файл задаётся в параметре list-file. В режиме обновления указывать пространство и родительскую страницу не нужно.
Изображения загружаются во вложения Confluence под теми именами, которые имеют их файлы. Поэтому, в одной странице не должно быть изображений, файлы которых имеют одинаковое имя.
Если при загрузке файла изображения во вложениях страницы уже имеется файл с таким же именем, будет выполнено обновление. Перед обновлением сверяются sha1-хэши файлов, и обновление выполняется только в том случае, если они различаются. Если установлено, что файл всё же изменился, он загружается во вложения Confluence под тем же именем, При этом возникает новая версия данного вложения и она становится текущей. Во всех версиях самой страницы, где используется это изображение, будет отображаться именно текущая версия.
Удаления вложений, которые более не упоминаются в странице, система не выполняет, но выводит информационное сообщение о наличии таких вложений. При этом учитывается только текущая публикуемая версия страницы. Если вложение упоминается в предыдущих версиях страницы, а в текущей его нет, оно будет обозначено как неиспользуемое.
При загрузке вложений сверки по их контенту не происходит. Поэтому, при переименовании файла изображения произойдёт загрузка нового вложения, а вложение под старым именем останется, но может стать неиспользуемым.
Иногда нужно получить в Confluence более широкую таблицу, чтобы объёмное содержимое более удачно помещалось в ячейках и не возникало лишних переносов в строках. Для этого к таблице нужно указать специальный атрибут wide. Вместе с тем можно использовать и другие стандартные атрибуты, предусмотренные в Asciidoctor, например, cols для указания относительных ширин колонок.
[wide="true", cols="4,6"]
|===
|Ячейка 1 |Ячейка 2
|===Примечания (Admonitions) используются для смыслового выделения фрагментов текста. Набор доступных примечаний в Asciidoctor не идентичен вариантам, имеющимся в Confluence. Вариант для Confluence выбирается на основании таблицы:
| Asciidoctor | Confluence | Описание |
|---|---|---|
NOTE |
info |
Выделение голубым фоном. Применяется для нейтральных полезных дополнений и примечаний. |
TIP |
tip |
Выделение зелёным фоном. Можно использовать для определений, или для обозначения выполненных частей задачи. |
IMPORTANT |
note |
Выделение жёлтым фоном. Используется для привлечения внимания к важной информации. |
CAUTION, WARNING |
warning |
Выделение красным фоном. Самое заметное выделение, применяется для предостережений. Обозначает информацию, требующую особого внимания. |
- Страница
-
Она же 'страница Confluence' (по-английски 'page'), базовая единица публикации, которой оперирует данная программа. Иногда в качестве синонима может использоваться 'статья', но 'страница' предпочтительнее, так как 'статья' — это уже, скорее, про содержимое, а с точки зрения публикации важен лишь механический аспект.
- Заголовок
-
Или название страницы. В Asciidoc-документе — это рубрика первого уровня. В Confluence заголовок страницы не содержится в содержимом самой страницы, но обязательно выводится в верхней части страницы при просмотре. Также в Confluence заголовок в пределах пространства (space) должен быть уникален, по нему возможен поиск страницы при обращении через API.