GitLab Flavored Markdown 形式の数式を含む Markdown 文書を Pandoc で PDF に変換する

この記事のまとめ：
  • GitLab Flavored Markdown 形式の数式を含む Markdown ファイルを PDF に変換する方法を紹介しています。
  • GitLab CI でリポジトリー内の Markdown ファイルを PDF に自動的に変換する方法を紹介しています。
背景

最近、主に利用している Git ホスティングサービスを GitHub から GitLab に移行しています。それに伴って１つ困っていたことがありまして、それは GitLab 用に Markdown 形式で書いていた文書の PDF 化です。

GitLab のリポジトリー内にある Markdown は数式込みでプレビューできるので、意気揚々と数式を書きまくっていました。しかし、GitLab ではクライアント端末の過負荷防止のために、数式のレンダリングに２秒以上掛かる場合はそこで表示を止めてしまう仕様になっています。表示できないのであれば、 GitLab-CI を使ってリポジトリーにプッシュした Markdown 文書を自動的に PDF に変換したかったというのが背景です。

Pandoc での GitLab Flavored Markdown の PDF 化の流れ

簡単にさまざまな文書のフォーマットを変換するツールと言えば、 Pandoc があります。 Pandoc などで Markdown から PDF に変換するくらいであれば簡単にできそうなものですが、GitLab の数式フォーマットは少し特殊です。この特殊フォーマットは GitLab Flavored Markdown と言い、GitLab 独自のフォーマットになっています。そのため、 Pandoc で Markdown を PDF に変換しようと思っても数式だけは変換してくれません。

試行錯誤の上、１つの解決策を見つけましたので紹介します。主に用いるものは次のとおりです。

今回は最後の LuaLaTeX 用のフィルターが非常に重要な役割でした。今のところうまく動いています。

ちなみに、このフィルターを見つけてくるまでに、さまざまやりました。 Markdown → PDF の変更のために Pandoc のオプションを変更してみたものの GitLab Flavored Markdown の数式ブロックはまったく認識してくれませんでした。また、普段 Markdown の作成は VS Code に Markdown+Math という extension を使って GitLab 用の Markdown の作成をしているのですが、 Markdown Math では HTML 出力ができます。そのため、 Markdown → HTML → PDF で変換することもやってみましたが、なぜか数式用の文字コードを認識してくれず PDF で文字化けし、これもダメでした。

それでは上記のとおりに作成したファイル類は次のリポジトリーと、コンテナーはコンテナーレジストリーに置いてあります。

hassiweb-programming / GitLab Flavored Markdown to PDF

GitLab Flavored Markdown を PDF に変換する CI

Docker イメージの作成

GitLab-CI で動かすのでまずは Docker イメージを作成します。 Docker イメージを作成する際、TeX のフルサイズのスキームをインストールするとファイルサイズが非常に大きいので、scheme-full から作ったイメージ（full.Dockerfile：約 4.2 GB）と scheme-basic をもとに作ったイメージ（small.Dockerfile：約 1.8 GB）の２つを用意しました（それでも大きい…）。

基本的な流れは、TeX Live のインストール、Pandoc のインストール、LuaLaTeX 用のフィルターをコピーしているだけです。

TeX Live と Pandoc は簡単にバージョン変更ができるように、パッケージマネージャーを使わずにインストールしています。それぞれのバージョンの値を入れている環境変数を変更すれば、バージョン変更ができます。

なお、TeX の scheme-basic ベースで作ったコンテナーの検証が十分にできていなません。テスト用の Markdown の PDF 変換はできていますが、もしかすると条件によっては必要なスタイルファイルが足りないかもしれません。その際はエラーメッセージから必要なスタイルファイルが含まれているパッケージを次のコマンドで探し、表示されたパッケージをインストールすればよいです。

tlmgr search --file --global '***.sty'
GitLab CI

GitLab CI で、上記で作成した Docker イメージを利用して、リポジトリーにある Markdown ファイルを自動的に PDF に変換します。GitLab CI で変換した PDF ファイルは、 GitLab CI の成果物 (artifact) として取得できます。実際の操作としては GitLab のプロジェクトページのメニューから “CI/CD” → “Jobs” → 完了したジョブを選択 → “Job artifacts” (下図赤枠) を選択すればダウンロードやブラウザーでの表示ができます。

gitlab-ci.yml を書く際は、次のように artifacts の構文を使えばよいです。こちらのスクリプトでは、docs/ 内に含まれるすべての .md ファイルを PDF に変換します。変換した PDF ファイルすべてをこのジョブでの artifact としていることになります。

md2pdf:
    stage: pandoc-convert
    image: registry.gitlab.com/hassiweb-programming/md2pdf/pandoc-latex-small:$IMAGE_VERSION
    variables:
        PANDOC_OPTIONS: "-s --pdf-engine=lualatex -V documentclass=ltjsarticle -V classoption=pandoc --lua-filter /opt/lualatex/filter/gitlab-math.lua"
    script:
        - set +e
        - mkdir ./artifacts
        - files="docs/*.md"
        - for filepath in $files; do
        -   pandoc $filepath -o $filepath.pdf ${PANDOC_OPTIONS}
        - done
    artifacts:
        paths:
            - "docs/*.pdf"

こんな感じで GitLab CI を使ってリポジトリー内にある Markdown を PDF に自動的に変換できます。ただ、いくつか使ってみているものの、フィルターの定義が不十分なのかいくつかよくわからない理由でエラーが出たりするので、しばらく使ってみて調整が必要かもしれません。

参考記事

今回はいろいろな記事を参考にさせていただきました。

ついでに、VS Code でも Markdown から PDF に変換できるようなので GitLab CI も面倒くさくなればこちらを試すかも。


今回は以上です。 最後まで読んでいただき、ありがとうございます。
関連記事

GitLab CI/CD と Textlint で Markdown 形式の技術文書を自動的に校正する

文書校正ツールの textlint とそのプラグインの概要を紹介します。textlint を使える Dockerfile と GitLab CI のサンプルコードを紹介します



コメント

コメントを投稿

このブログの人気の投稿

LinuxでのnVidia GPUのオーバークロック・電力チューニング方法

この記事のまとめ： Linux (Ubuntu 16.04)環境でのnVidia GPUのオーバークロックの方法や、消費電力に対するパフォーマンスを最大化するためのチューニング方法をまとめています。 背景： Linux (Ubuntu 16.04)環境でnVidia製GPUを使って仮想通貨のマイニングを行っていまして、収益を最大化するために供給電力やオーバークロックなどのチューニングをしてみました。なお、オーバークロックはGPUドライバーのクラッシュや最悪の場合、GPUの故障を引き起こす可能性がありますので、自己責任で実行してください。
続きを読む