Utwórz łańcuch publikacji za pomocą Pandoc i Docker

Dzisiaj przyjrzymy się bliżej, w jaki sposób profesjonaliści mogą skorzystać z pomocy Pandoc, aby stworzyć solidny i łatwy do wdrożenia łańcuch publikacji. Pandoc to niezwykle proste, ale potężne narzędzie, które pozwala użytkownikom konwertować dokumenty na różne formaty, w zależności od ich wymagań.

Może znacznie uprościć dokumentację i publikację, a nawet otworzyć kilka nowych możliwości automatyzacji. Co najlepsze, Pandoc opiera się na przyjaznym dla Git Markdown, co oznacza, że ​​możesz również zaimplementować system kontroli wersji dla swojej dokumentacji bez żadnych dodatkowych kłopotów.

Mówiąc o kłopotach, będziemy polegać na obrazie Dockera, aby zainstalować Pandoc i LaTeX za pomocą prostego pociągnięcia. Instalowanie oprogramowania może być czasochłonne, a konfigurowanie działającego środowiska oprogramowania od zera podczas rozpoczynania nowego projektu jest mało produktywne. Docker pomaga złagodzić te problemy, umożliwiając użytkownikom skonfigurowanie wszystkiego w ciągu kilku minut, niezależnie od platformy.

Ponadto często zdarza się, że pracodawcy wymagają dostarczenia własnego sprzętu komputerowego. Jest to często określane jako Bring Your Own Device (BYOD) i nie zapominajmy, że pandemia COVID-19 sprawiła, że ​​praca w domu stała się znacznie bardziej powszechna. Bez rozwiązań takich jak Docker trudno byłoby obsługiwać aplikacje działające na zróżnicowanym sprzęcie i systemach operacyjnych, takich jak Windows, macOS i Linux.

Zacznijmy od przyjrzenia się bliżej kontenerom i obrazom Dockera, zanim przejdziemy do Pandoc.

Doker na ratunek

Korzystanie z kontenerów Docker może wyeliminować potrzebę instalowania wielu aplikacji na nowym komputerze. Gotowe obrazy platformy Docker są dostępne w usłudze Docker Hub dla dużej liczby aplikacji. Wiodący dostawcy usług w chmurze, tacy jak AWS, Azure i Google, udostępniają rejestry kontenerów. Istnieje wiele innych rejestrów innych firm, w tym GitLab i Red Hat OpenShift.

Obraz prawdopodobnie będzie dostępny dla większości (jeśli nie wszystkich) aplikacji. Oznacza to, że nie jest konieczne instalowanie większości aplikacji i ich zależności. Aplikację można po prostu uruchomić w kontenerze Docker. To dogodnie eliminuje problemy związane z członkami zespołu uruchamiającymi aplikacje na różnym sprzęcie i w różnych systemach operacyjnych. Ten sam obraz może być używany do uruchamiania kontenerów w dowolnym systemie, w którym można je uruchomić, a specjaliści Docker mogą sprawić, że proces ten będzie niezwykle szybki i wydajny.

Przypadek użycia Pandoc: Dokumentacja

Może być wymagana dokumentacja w kilku różnych formatach. Ten sam dokument może wymagać dostępności w różnych formatach, takich jak HTML do prezentacji i PDF do materiałów informacyjnych. Konwersja między formatami plików może być żmudna i zajmuje dużo czasu. Dobrym rozwiązaniem jest posiadanie łańcucha publikacji z jednym źródłem prawdy. Wszystkie dokumenty powinny być napisane w tym samym języku. Powinien to być język tekstowy, ponieważ łatwiej jest go wersjonować i przechowywać w repozytoriach Git.

Markdown to dobry wybór do stworzenia jednego źródła prawdy. Oprogramowanie, które może konwertować dokumenty Markdown na wiele innych formatów, jest łatwo dostępne i zwykle jest niezawodne.

Pandoc

Pandoc to pakiet oprogramowania, który może konwertować dokumenty na różne formaty. W szczególności może konwertować Markdown do HTML, PDF i innych powszechnie używanych formatów. Proces konwersji można dostosować za pomocą szablonów i metadanych w źródle Markdown.

Pandoc wymaga instalacji LaTeX do tworzenia plików PDF. Instalacja Pandoca i LaTeX-a jest dość czasochłonna. Na szczęście istnieje obraz Docker o nazwie pandoc/latex , który eliminuje potrzebę instalowania czegokolwiek innego niż Docker.

Polecenia dokowane

Należy znaleźć lub utworzyć odpowiedni obraz Dockera, który zawiera niezbędne oprogramowanie. Zaleca się pobranie obrazu do rejestru lokalnego, ponieważ pobieranie może zająć trochę czasu.

 docker pull pandoc/latex

Uruchomienie polecenia w kontenerze Docker wymaga opakowania do uruchomienia kontenera Docker i wykonania polecenia w kontenerze. Dobrym rozwiązaniem jest napisanie funkcji powłoki w systemie macOS lub UNIX/Linux. Funkcję można umieścić w dowolnych skryptach logowania lub w osobnym pliku, takim jak $HOME/.functions . Możliwe jest również napisanie skryptu lub aliasu o tej samej funkcjonalności.

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

Ta funkcja wykonuje następujące czynności:

• Drukuje polecenie na ekranie.
• Uruchamia kontener Docker z obrazu pandoc/latex .
• Opcja -it tworzy interaktywną sesję terminala i sprawia, że ​​dane wyjściowe polecenia są widoczne.
• Opcja --rm usuwa kontener po zakończeniu polecenia.
• Opcja -v $PWD:/work podłącza bieżący katalog na hoście do katalogu /work w kontenerze.
• Opcja -w /work sprawia, że ​​katalog /work w kontenerze staje się katalogiem roboczym.
• Ostatni pandoc "$@" uruchamia polecenie pandoc w kontenerze, przekazując wszystkie opcje wiersza poleceń przekazane do funkcji.

Powłoka lub skrypt musi załadować funkcję do pamięci.

 . $HOME/.functions

Funkcja jest teraz samodzielnym poleceniem i zachowuje się tak samo, jak gdyby plik binarny pandoc został zainstalowany lokalnie. Takie podejście można zastosować do dowolnego polecenia dostępnego w obrazie platformy Docker.

Przecena do HTML

Aby przekonwertować Markdown na HTML, lepiej użyć szablonu i metadanych w Markdown.

Metadane przecen

Źródło Markdown może mieć sekcję nagłówka, która może zawierać dowolne metadane. Metadane mają postać par klucz-wartość. Wartości można podstawić w szablonie HTML.

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

Nagłówek zaczyna się od linii zawierającej tylko trzy myślniki --- . Jest zakończony linią zawierającą tylko trzy kropki ... . Klucze to pojedyncze słowa, po których następuje dwukropek i jego wartość. Klucze można zagnieżdżać. Przykład pokazuje definicję kluczy o nazwie title, links.prev i links.next .

To podejście wykorzystuje osobny plik dla każdej strony. W tym przykładzie poprzednia strona to index.md , bieżąca strona to page001.md , a następna strona to page002.md . W praktyce używane byłyby bardziej znaczące nazwy plików, aby łatwiej było zmieniać kolejność i wstawiać strony.

Szablon HTML

Szablon HTML to po prostu plik HTML. Zastępowanie metadanych i proste struktury kontrolne można dodawać między symbolami dolara. Oto prosty przykład szablonu HTML dla 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>

Przykład pokazuje szablon. $body$ zostaje zastąpiony tekstem Markdown przekonwertowanym na HTML. Instrukcje warunkowe generują łącze HTML tylko wtedy, gdy metadane są zdefiniowane w nagłówku Markdown.

Generowanie HTML z Markdown

Trzeba tylko powiedzieć Pandocowi, jak nazywają się pliki wejściowe i wyjściowe, plus wszelkie pliki szablonów. Domyślny format pliku wejściowego to Markdown . Może wywnioskować format pliku wyjściowego z określonego rozszerzenia pliku wyjściowego.

Polecenia do generowania danych wyjściowych mogą być skryptem lub plikiem makefile.

 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

Dla każdego pliku .md w katalogu Project tworzy odpowiedni plik .html w katalogu HTML/Project , jeśli plik wyjściowy jest starszy niż plik wejściowy lub nie istnieje.

Generowanie Beamer PDF z Markdown

Beamer to pakiet LaTeX do produkcji prezentacji. Wynikiem jest pokaz slajdów w formacie PDF.

Te same pliki źródłowe Markdown mogą być użyte do wygenerowania rzutnika PDF.

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

Szczegóły polecenia to:

• Opcja -t beamer mówi, że użyj LaTeX-a i beamera do wygenerowania pliku PDF.
• Opcja -o określa plik wyjściowy.
• Opcje -V wybierają motyw rzutnika i motyw kolorystyczny.
• Polecenie kończy się listą plików Markdown, które zostaną połączone w podanej kolejności.

Całe przetwarzanie odbywa się w kontenerze Docker.

Przecena do PDF

Konwersja dokumentu Markdown na dokument PDF jest również dość prosta. PDF jest zawsze generowany przez konwersję Markdowna na LaTeX. Metadane można dodać do nagłówka Markdown, aby dostosować dane wyjściowe, takie jak ustawienie rozmiaru papieru i rozmiaru marginesów.

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

Generowanie PDF z Markdown

Polecenie konwersji Markdown do formatu PDF jest proste:

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

Opcja -s tworzy samodzielny dokument.

Wniosek

Nie trzeba już spędzać wielu dni na instalacji oprogramowania. Proste uruchomienie polecenia w kontenerze Dockera eliminuje potrzebę instalacji. Wiele aplikacji ma odpowiednie obrazy Docker w Docker Hub. Jeśli oprogramowanie wymaga aktualizacji, po prostu pobierz najnowszy obraz platformy Docker.

Konfiguracja nowego komputera to tylko kwestia zainstalowania Dockera, pobrania niezbędnych obrazów i stworzenia kilku skryptów.

Nie ma już potrzeby tworzenia dokumentów w różnych formatach. Dla wszystkich dokumentów można używać jednego formatu, takiego jak Markdown. Narzędzia takie jak Pandoc mogą następnie generować dokumenty z Markdown do wielu różnych formatów.

Ponieważ Markdown jest plikiem tekstowym, po zaewidencjonowaniu w repozytorium Git dostępna jest pełna historia wersji. Repozytoria Git również automatycznie renderują Markdown i umożliwiają użytkownikom komentowanie zmian bez konieczności używania niechlujnej historii zmian w samym pliku dokumentu.