Найти в Дзене
LITVINOV-UPGRADE-LINUX

Конвертация AsciiDoc в формат PDF в Astra Linux

Файл с расширением ADOC - это AsciiDoc файл, текстовый документ, использующий формат AsciiDoc для разметки. AsciiDoc похож на Markdown и предназначен для создания документации, статей, книг и других типов документов. Он поддерживает различные элементы форматирования, такие как заголовки, списки, ссылки, изображения, таблицы и математические формулы. Этот формат очень удобен для совместного оформления документации для ПО. Он содержит описание текста, таблиц и форматирования при момощи ascii символов, что позволяет легко его интегрировать с git Для публичного просмотра, можно генерить pdf файлы, это можно делать в ручную или использовать методы CI/CD. Рассмотрим способ ручной сборки. Добавляем текущего пользователя в группу docker
sudo usermod -aG docker $USER
Применяем изменения (может потребоваться перезагрузка или выход из сеанса)
newgrp docker
Проверяем
groups
Asciidoctor - это текстовый процессор и набор инструментов для публикации, который преобразует разметку AsciiDoc в различн
Оглавление

Вступление

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

Этот формат очень удобен для совместного оформления документации для ПО. Он содержит описание текста, таблиц и форматирования при момощи ascii символов, что позволяет легко его интегрировать с git

Для публичного просмотра, можно генерить pdf файлы, это можно делать в ручную или использовать методы CI/CD. Рассмотрим способ ручной сборки.

Установка Docker

Добавляем текущего пользователя в группу docker
sudo usermod -aG docker $USER

Применяем изменения (может потребоваться перезагрузка или выход из сеанса)
newgrp docker

Проверяем
groups

Установка Asciidoctor

Asciidoctor - это текстовый процессор и набор инструментов для публикации, который преобразует разметку AsciiDoc в различные форматы, включая HTML, PDF, DocBook и другие

Скачиваем официальный образ Asciidoctor
$ sudo docker pull asciidoctor/docker-asciidoctor

# Проверяем
$ docker images | grep asciidoctor
asciidoctor/docker-asciidoctor latest c651f1c01e9a 3 days ago 1.36GB

Структура каталога с проектом ADOC

Для удобства можно делить документ на отдельные страницы, по форматированию я сделаю отдельную статью

Но общая структура примерно такая, скриншоты и иллюстрации хранятся в отдельной папке и их удобно передавать техническому писателю.

-2

Запуск сборки.

sudo docker run --rm -v $(pwd):/documents/ asciidoctor/docker-asciidoctor asciidoctor-pdf ./3dserver-admin-manual.adoc -o outbox/3dserver-admin-manual-v1.0.2.pdf

В результате сборки получаем в папке output, файл с 3dserver-admin-manual-v1.0.2.pdf

Итоговый pdf нам не нужен в репозитории, поэтому в .gitignore добавим строчку:
**/outbox/*


Редактирование ADoc


В программе VSCode есть плагин, который позволяем просматривать форматирование AsciiDoc.

инструкция к плагину к плагину

AsciiDoc - Visual Studio Marketplace

Для установки под Astra Linux я использую скрипт, т.к. в AstraLinux 1.7 не хватало одной зависимости для запуска.


git clone https://gitflic.ru/project/litvinov_mv/astra-linux-vscode.git
cd astra-linux-vscode/
bash install-vscode.sh


Подключение AsciiDoc плагина

В среде VSCode нажимаем:
Ctrl + P

ext install asciidoctor.asciidoctor-vscode
-3

[install] plugin

Для просмотра preview ADOC используем сочетание клавиш:
Ctrl+Shift+V - preview

Полезные ссылки

Что такое AsciiDoc
Использование AsciiDoc для управления документацией на проекте (Часть 2)
Asciidoc для ЕСКД
AsciiDoc - Visual Studio Marketplace