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

この記事のまとめ：

GitLab Flavored Markdown 形式の数式を含む Markdown ファイルを HTML 経由で PDF に変換する方法を紹介しています。
GitLab CI でリポジトリー内の HTML ファイルを PDF に自動的に変換する方法を紹介しています。

背景

つい先日、この記事とよく似たテーマの記事を書きました。これです。

GitLab Flavored Markdown 形式の数式を含む Markdown 文書を直接 PDF に変換しようというものです。しばらく、これを使って Markdown を PDF に変換して使っていました。しかし、少し使ってみると２つほど問題が見つかったのですが、解決策がいまだ見当たらないという情けない状況になってしまいました…。少し手間どりそうだったため、別の策として HTML を経由して、 PDF に変換することにしてみました。

ちなみに問題は次のとおりです。

Pandoc は Markdown を PDF に変換する際、一度 TeX に変換して PDF に変換しますが、TeX への変換がうまくいかないことがあるようで、TeX の文法エラーが出てくる
インライン数式の場合にのみ一部の Unicode 文字の記号が見つからない

PDF 化の流れ

前の記事で PDF 化するために Pandoc を使っていましたが、今回は使用しません。大まかな流れは次の通りです。

VS Code 用 Extension の Markdown+Math で Markdown を HTML で保存
Chromium で HTML を PDF として保存

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

Markdown から HTML への変換

私は GitLab 用の数式込みの Markdown 文書を作成する際には、VS Code と Markdown+Math の extension を使用して作成します。この Markdown+Math には HTML で保存する機能があります。そのため、Markdown で文書を作成していれば自動的に HTML もできあがります。

HTML に保存する際、CSS の設定ができます。 “Extension settings” の “Mdmath: Style” の項目に CSS のファイルパスを書き込むだけです。ファイル名だけ指定すればカレントディレクトリー内の指定したファイルを参照します。たとえば、mdmath.css と書けば、HTML では次のように CSS を読み込むタグが追加されます。

<link rel="stylesheet" href="mdmath.css">

Pandoc の場合は TeX のスタイルファイルを用意しなければならいので、少し面倒でしたが、この場合は出力したいフォーマットを CSS で設定できるので便利です。

HTML から PDF への変換

前の記事にも HTML から PDF への変換を試していたのですが、その際は Pandoc を使っていました。ただ、うまく Pandoc を使いこなせず、数式に使用されている Unicode 文字がうまく読み込まれず失敗していました。そこで、今回は Chromium （のヘッドレスモード）を利用します。やっぱり HTML を扱うには Web ブラウザーの方が楽ちんだったという感じです。 GitHub で pinkeen/docker-html-to-pdf として Chromium で PDF に変換するための Docker コンテナーを公開されている方がおられましたのでそれを利用させていただきました。ただ、日本語の文書を PDF 化したかったのですが、そのままでは日本語フォントが入っていませんので、日本語フォントのインストールだけ追加でします。

できあがった Dockerfile と Docker コンテナーのレジストリーは、それぞれのリンク上にあります。この Dockerfile では、Noto フォントをインストールしています。

GitLab CI でリポジトリー内の HTML ファイルを PDF に変換

最後に、これらを利用して GitLab CI で自動的にリポジトリー内の HTML ファイルを PDF に変換します。

.gitlab-ci.yml の中から PDF に変換しているところは次のところです。

html2pdf:
    stage: convert
    image: 
        name: registry.gitlab.com/hassiweb-programming/html2pdf/chrome-headless-render-pdf-ja:$IMAGE_VERSION
        entrypoint: [""]
    variables:
        DIR: test
    script:
        - set +e # disable exit on error
        - files="$DIR/*.html"
        - for filepath in $files; do
        -   echo Converting $filepath
        -   /usr/local/bin/entrypoint --url file://$PWD/$filepath --pdf $filepath.pdf
        - done
    artifacts:
        paths:
            - "$DIR/*.pdf"

今回は７行目の DIR という変数に HTML ファイルが入っているディレクトリーを指定しています。もし、流用される場合にはリポジトリー構成に応じて、ここの値を変更すればよいです。

なお、CI のスクリプトを動かすうえで、このコンテナーには ENTRYPOINT が設定されているため、それを無効化しないと使えないため、５行目のようにして ENTRYPOINT の無効化しています。

13 行目で HTML を PDF に変更するコマンドを実行しています。コマンドラインオプションはこちらから確認できます。なお、デフォルト設定では CSS として background の設定がされていても無効化されるようになっていますので、必要に応じてオプションを変更する必要があります。

うまく変換されれば artifacts として PDF ファイルが取得できます。テスト用の HTML ファイルの変換結果はこちらです。

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

Search This Blog