PandocとDockerでパブリケーションチェーンを作成する

公開: 2022-03-11

今日は、専門家がPandocの助けを借りて、堅牢で実装が簡単なパブリケーションチェーンを作成する方法を詳しく見ていきます。 Pandocは非常にシンプルでありながら強力なツールであり、ユーザーは要件に応じてドキュメントをさまざまな形式に変換できます。

これにより、ドキュメントと公開が大幅に簡素化され、さらにはいくつかの新しい自動化の可能性が開かれます。 何よりも、PandocはGitに適したマークダウンに依存しています。つまり、追加の手間をかけずに、ドキュメントのバージョン管理システムを実装することもできます。

面倒と言えば、単純なプルでPandocとLaTeXをインストールするためにDockerイメージに依存します。 ソフトウェアのインストールには時間がかかる可能性があり、新しいプロジェクトを開始するときに最初から動作するソフトウェア環境をセットアップすることはほとんど生産的ではありません。 Dockerは、プラットフォームに関係なく、ユーザーがすべてを数分でセットアップできるようにすることで、これらの問題を軽減するのに役立ちます。

さらに、雇用主があなた自身のコンピュータハードウェアを提供することを要求することは珍しいことではありません。 これは、Bring Your Own Device（BYOD）と呼ばれることが多く、COVID-19の大流行により、自宅での作業がはるかに普及していることを忘れないでください。 Dockerのようなソリューションがなければ、Windows、macOS、Linuxなどのさまざまなハードウェアやオペレーティングシステムで実行されているアプリケーションをサポートすることは困難です。

Pandocに進む前に、Dockerコンテナとイメージを詳しく見ていきましょう。

Docker to the Rescue

Dockerコンテナーを使用すると、新しいマシンに複数のソフトウェアアプリケーションをインストールする必要がなくなります。 ビルド済みのDockerイメージは、多数のアプリケーションのDockerHubで利用できます。 AWS、Azure、Googleなどの主要なクラウドプロバイダーはすべて、コンテナーレジストリを提供しています。 GitLabやRedHatOpenShiftなど、他にも多くのサードパーティレジストリがあります。

画像は、すべてではないにしてもほとんどのアプリケーションで利用できる可能性があります。 これは、ほとんどのアプリケーションとその依存関係をインストールする必要がないことを意味します。 アプリケーションは、Dockerコンテナで簡単に実行できます。 これにより、さまざまなハードウェアおよびさまざまなオペレーティングシステムでアプリケーションを実行しているチームメンバーに関連する問題が簡単に解消されます。 同じイメージを使用して、コンテナーを実行できる任意のシステムでコンテナーを実行できます。Dockerスペシャリストは、このプロセスを非常に高速かつ効率的にすることができます。

Pandocのユースケース：ドキュメント

いくつかの異なる形式のドキュメントが必要になる場合があります。 同じドキュメントを、プレゼンテーション用のHTMLや配布用のPDFなど、さまざまな形式で利用できるようにする必要がある場合があります。 ファイル形式間の変換は面倒で、多くの時間を必要とする場合があります。 良い解決策は、信頼できる唯一の情報源を持つ出版チェーンを持つことです。 すべての文書は同じ言語で書かれている必要があります。 バージョン管理とGitリポジトリへの保存が簡単なため、テキストベースの言語にする必要があります。

マークダウンは、信頼できる唯一の情報源を作成するための良い選択です。 Markdownドキュメントを他のさまざまな形式に変換できるソフトウェアはすぐに利用でき、信頼できる傾向があります。

マークダウンは、さまざまな用途のためにさまざまな形式に簡単に変換できます
マークダウンは、さまざまな用途のためにさまざまな形式に簡単に変換できます。

Pandoc

Pandocは、ドキュメントをさまざまな形式に変換できるソフトウェアパッケージです。 特に、MarkdownをHTML、PDF、およびその他の広く使用されている形式に変換できます。 変換プロセスは、Markdownソースのテンプレートとメタデータを使用してカスタマイズできます。

Pandocでは、PDFファイルを作成するためにLaTeXをインストールする必要があります。 PandocとLaTeXのインストールにはかなりの時間がかかります。 幸い、 pandoc /ラテックスと呼ばれるDockerイメージがあり、Docker以外のものをインストールする必要がありません。

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 "$@" }

この関数は次のことを行います。

  • コマンドを画面に出力します。
  • pandoc/latexイメージからDockerコンテナを実行します。
  • -itオプションは、対話型ターミナルセッションを作成し、コマンドの出力を表示します。
  • --rmオプションは、コマンドが終了するとコンテナを削除します。
  • -v $PWD:/workオプションは、ホスト上の現在のディレクトリをコンテナ内のディレクトリ/workにマウントします。
  • -w /workは、コンテナ内の/workディレクトリを作業ディレクトリにします。
  • 最後のpandoc "$@"は、コンテナ内でpandocコマンドを実行し、関数に渡されたすべてのコマンドラインオプションを渡します。

シェルまたはスクリプトは、関数をメモリにロードする必要があります。

 . $HOME/.functions

この関数はそれ自体がコマンドになり、 pandocバイナリがローカルにインストールされている場合と同じように動作します。 このアプローチは、Dockerイメージで使用可能なすべてのコマンドに使用できます。

HTMLへのマークダウン

MarkdownをHTMLに変換するには、Markdownでテンプレートとメタデータを使用することをお勧めします。

HTMLへのマークダウン

マークダウンメタデータ

Markdownソースには、任意のメタデータを持つことができるヘッダーセクションを含めることができます。 メタデータは、キーと値のペアの形式を取ります。 値は、HTMLテンプレートで置き換えることができます。

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

ヘッダーは、3つのダッシュのみを含む行で始まります--- 。 3つのドットのみを含む行で終了し... キーは、コロンとその値が後に続く単一の単語です。 キーはネストできます。 この例は、 title, links.prev 、 links.nextというキーの定義を示しています。

このアプローチでは、ページごとに個別のファイルを使用します。 この例では、前のページはindex.md 、現在のページはpage001.md 、次のページはpage002.mdです。 実際には、ページの並べ替えや挿入が簡単になるように、より意味のあるファイル名が使用されます。

HTMLテンプレート

HTMLテンプレートは、単なるHTMLファイルです。 メタデータの置換と単純な制御構造をドル記号の間に追加できます。 PandocのHTMLテンプレートの簡単な例を次に示します。

 <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$は、HTMLに変換されたMarkdownテキストに置き換えられます。 条件ステートメントは、メタデータがMarkdownヘッダーで定義されている場合にのみHTMLリンクを生成します。

MarkdownからのHTMLの生成

Pandocは、入力ファイルと出力ファイルの名前に加えて、テンプレートファイルを通知する必要があります。 デフォルトの入力ファイル形式はMarkdownです。 指定された出力ファイル拡張子から出力ファイル形式を推測できます。

出力を生成するコマンドは、スクリプトまたは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

出力ファイルが入力ファイルより古いか存在しない場合、Projectディレクトリ内のすべての.mdファイルに対して、対応する.htmlファイルがHTML/Project Projectに作成されます。

MarkdownからBeamerPDFを生成する

Beamerは、プレゼンテーションを作成するためのLaTeXパッケージです。 出力はPDFスライドショーです。

MarkdownからBeamerPDFを生成する

同じ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 ...

MarkdownからPDFを生成する

マークダウンをPDFに変換するコマンドは簡単です。

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

-sオプションは、スタンドアロンドキュメントを作成します。

結論

ソフトウェアのインストールに何日も費やす必要はなくなりました。 Dockerコンテナーでコマンドを実行するだけで、インストールの必要がなくなります。 多くのアプリケーションには、DockerHubに適切なDockerイメージがあります。 ソフトウェアを更新する必要がある場合は、最新のDockerイメージをプルするだけです。

新しいコンピューターのセットアップは、Dockerをインストールし、必要なイメージをプルして、いくつかのスクリプトを作成するだけです。

異なる形式でドキュメントを作成する必要がなくなりました。 Markdownなどの単一のフォーマットをすべてのドキュメントに使用できます。 Pandocなどのツールは、Markdownから多数の異なる形式にドキュメントを生成できます。

Markdownはテキストファイルであるため、Gitリポジトリにチェックインすると、完全なバージョン履歴が利用可能になります。 また、Gitリポジトリは自動的にマークダウンをレンダリングし、ドキュメントファイル自体で厄介な変更履歴を使用せずに変更にコメントできるようにします。