Создайте цепочку публикаций с Pandoc и Docker

Сегодня мы более подробно рассмотрим, как профессионалы могут заручиться поддержкой Pandoc для создания надежной и простой в реализации цепочки публикаций. Pandoc — чрезвычайно простой, но мощный инструмент, который позволяет пользователям преобразовывать документы в различные форматы в зависимости от их требований.

Это может значительно упростить документацию и публикацию или даже открыть несколько новых возможностей автоматизации. Лучше всего то, что Pandoc полагается на Git-дружественный Markdown, что означает, что вы также можете внедрить систему контроля версий для своей документации без каких-либо дополнительных хлопот.

Говоря о хлопотах, мы будем полагаться на образ Docker для установки Pandoc и LaTeX простым нажатием. Установка программного обеспечения может занять много времени, а настройка рабочей программной среды с нуля при запуске нового проекта вряд ли будет продуктивной. Docker помогает смягчить эти проблемы, позволяя пользователям настроить все за считанные минуты, независимо от платформы.

Кроме того, нередко работодатели требуют, чтобы вы предоставили собственное компьютерное оборудование. Это часто называют «принеси свое собственное устройство» (BYOD), и давайте не будем забывать, что пандемия COVID-19 сделала работу из дома гораздо более распространенной. Без таких решений, как Docker, было бы сложно поддерживать приложения, работающие на различных аппаратных средствах и операционных системах, таких как Windows, macOS и Linux.

Давайте начнем с более подробного изучения контейнеров и образов Docker, прежде чем перейти к Pandoc.

Докер спешит на помощь

Использование контейнеров Docker может устранить необходимость установки нескольких программных приложений на новую машину. Готовые образы Docker доступны на Docker Hub для большого количества приложений. Ведущие поставщики облачных услуг, такие как AWS, Azure и Google, предоставляют реестры контейнеров. Существует множество других сторонних реестров, включая GitLab и Red Hat OpenShift.

Вполне вероятно, что образ будет доступен для большинства (если не для всех) приложений. Это означает, что нет необходимости устанавливать большинство приложений и их зависимостей. Приложение можно просто запустить в контейнере Docker. Это удобно устраняет проблемы, связанные с тем, что члены команды запускают приложения на различном оборудовании и в разных операционных системах. Один и тот же образ можно использовать для запуска контейнеров в любой системе, которая их поддерживает, и специалисты Docker могут сделать этот процесс чрезвычайно быстрым и эффективным.

Вариант использования Pandoc: документация

Документация может потребоваться в нескольких различных форматах. Один и тот же документ может быть доступен в разных форматах, таких как HTML для презентаций и PDF для раздаточных материалов. Преобразование между форматами файлов может быть утомительным и требовать много времени. Хорошее решение — иметь цепочку публикаций с одним источником правды. Все документы должны быть написаны на одном языке. Это должен быть текстовый язык, так как его легче создавать и хранить в репозиториях Git.

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

Пандок

Pandoc — это программный пакет, который может преобразовывать документы в различные форматы. В частности, он может конвертировать Markdown в HTML, PDF и другие широко используемые форматы. Процесс преобразования можно настроить с помощью шаблонов и метаданных в источнике Markdown.

Pandoc требует установки LaTeX для создания файлов PDF. Установка Pandoc и LaTeX занимает довольно много времени. К счастью, существует образ Docker с именем pandoc/latex , который избавляет от необходимости устанавливать что-либо, кроме Docker.

Докер-команды

Необходимо найти или создать подходящий образ Docker, содержащий необходимое программное обеспечение. Желательно загрузить образ в локальный реестр, так как загрузка может занять некоторое время.

 docker pull pandoc/latex

Для запуска команды в контейнере Docker требуется оболочка для запуска контейнера Docker и выполнения команды в контейнере. Хорошим решением этой проблемы является написание функции оболочки в системе macOS или UNIX/Linux. Функцию можно поместить в любые сценарии входа в систему или в отдельный файл, например $HOME/.functions . Также можно написать скрипт или псевдоним с той же функциональностью.

 function pandoc { echo pandoc $@ docker run -it --rm -v $PWD:/work -w /work pandoc/latex pandoc "$@" }

Эта функция делает следующее:

• Он выводит команду на экран.
• Он запускает контейнер Docker из pandoc/latex .
• Параметр -it создает интерактивный сеанс терминала и делает вывод команды видимым.
• Опция --rm удаляет контейнер после завершения команды.
• Параметр -v $PWD:/work монтирует текущий каталог на хосте в каталог /work в контейнере.
• Параметр -w /work делает каталог /work в контейнере рабочим каталогом.
• Последний pandoc "$@" запускает команду pandoc в контейнере, передавая все параметры командной строки, переданные функции.

Оболочке или сценарию необходимо загрузить функцию в память.

 . $HOME/.functions

Функция теперь является самостоятельной командой и ведет себя так же, как если бы бинарный файл pandoc был установлен локально. Этот подход можно использовать для любой команды, доступной в образе Docker.

Уценка в HTML

Чтобы преобразовать Markdown в HTML, лучше использовать шаблон и метаданные в файле Markdown.

Метаданные уценки

Источник Markdown может иметь раздел заголовка с произвольными метаданными. Метаданные имеют форму пар ключ-значение. Значения можно заменить в шаблоне HTML.

 --- title: Document title links: prev: index next: page002 ...

Заголовок начинается со строки, содержащей только три дефиса --- . Он завершается строкой, состоящей всего из трех точек ... . Ключи — это отдельные слова, за которыми следует двоеточие и его значение. Ключи могут быть вложенными. В примере показано определение ключей title, links.prev и links.next .

Этот подход использует отдельный файл для каждой страницы. В примере предыдущая страница — index.md , текущая страница — page001.md , а следующая страница — page002.md . На практике будут использоваться более осмысленные имена файлов, чтобы упростить изменение порядка и вставку страниц.

HTML-шаблон

Шаблон HTML — это просто файл HTML. Подстановка метаданных и простые управляющие структуры могут быть добавлены между символами доллара. Вот простой пример HTML-шаблона для Pandoc:

 <html> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>$title$</title> <link href="../css/style.css" type="text/css" rel="stylesheet" /> </head> <header> <h1>$title$</h1> </header> <body> $body$ </body> <footer> $if(links.prev)$ <a href="$links.prev$.html" class="previous">&laquo; Previous</a> $endif$ $if(links.next)$ <a href="$links.next$.html" class="next">Next &raquo;</a> $endif$ </footer> </html>

В примере показан шаблон. $body$ заменяется текстом Markdown, преобразованным в HTML. Условные операторы генерируют HTML-ссылку только в том случае, если метаданные определены в заголовке Markdown.

Генерация HTML из Markdown

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

Команды для создания выходных данных могут быть сценарием или make-файлом.

 dir=Project for input_file in ${dir}/*.md do output_file=HTML/${input_file%.md}.html if [[ ${input_file} -nt ${output_file} ]] then pandoc --data-dir . --template presentations.html -t html \ -o ${output_file} ${input_file} fi done

Для каждого файла .md в каталоге Project создается соответствующий файл .html в каталоге HTML/Project , если выходной файл старше входного или не существует.

Генерация Beamer PDF из Markdown

Beamer — это пакет LaTeX для создания презентаций. Результатом является слайд-шоу в формате PDF.

Те же исходные файлы Markdown можно использовать для создания PDF-файла для луча.

 pandoc -t beamer -o PDF/Project.pdf -V theme:Boadilla -V colortheme:whale Project/index.md Project/page000.md

Детали команды:

• Опция -t beamer указывает на использование LaTeX и beamer для создания PDF.
• Параметр -o указывает выходной файл.
• Параметры -V выбирают тему проектора и цветовую тему.
• Команда заканчивается списком файлов Markdown, которые будут объединены в указанном порядке.

Вся обработка выполняется внутри контейнера Docker.

Уценка в PDF

Преобразование документа Markdown в документ PDF также довольно просто. PDF всегда создается путем предварительного преобразования Markdown в LaTeX. Метаданные могут быть добавлены в заголовок Markdown для настройки вывода, например, для установки размера бумаги и размера полей.

 --- title: Title of document papersize: a4 geometry: - margin=20mm ...

Генерация PDF из Markdown

Команда для преобразования Markdown в PDF проста:

 pandoc -s Project/outline.md -o PDF/ProjectOutline.pdf

Параметр -s создает отдельный документ.

Заключение

Больше не нужно тратить много дней на установку программного обеспечения. Простой запуск команды в контейнере Docker устраняет необходимость установки. Многие приложения имеют подходящие образы Docker на Docker Hub. Если программное обеспечение нуждается в обновлении, просто скачайте последний образ Docker.

Настройка нового компьютера — это просто установка Docker, получение необходимых образов и создание нескольких сценариев.

Больше не нужно создавать документы в разных форматах. Один формат, такой как Markdown, может использоваться для всех документов. Такие инструменты, как Pandoc, могут затем генерировать документы из Markdown в большое количество различных форматов.

Поскольку Markdown — это текстовый файл, при возврате в репозиторий Git доступна полная история версий. Репозитории Git также автоматически отображают Markdown и позволяют людям комментировать изменения без необходимости использовать беспорядочную историю изменений в самом файле документа.