Markdownから自動でPDFを出力するGitHub Actionを作成した
LaTeXに詳しくない友人とちょっとした文書を共同で書くことになった。 お互いにちょうどよいのがMarkdownだと思ったのだが、いざPDF化してみようとするといろいろ難点があった。 そこで、GitHub ActionsでMarkdownを編集すると自動でLaTeX経由でPDF化するようなリポジトリを構築してGitHubのWebGUIでも編集でき、 もちろん従来のエディタでも編集できるようにした。
使用法
使用法について解説する。 まず、一般的なGitHub Actionsの使い方と同様に以下のようにファイルとディレクトリを配置する。
リポジトリのルートフォルダ/
┣ .github/
┃ ┗ workflows/
┃ ┗ main.yml
┃
┣ main.md
┗ .gitignoreとか
main.ymlを以下のように記述する。
github-emailとgithub-usernameは自分のものに置き換える必要がある。
# This is a basic workflow to help you get started with Actions
name: test
# Controls when the action will run. Triggers the workflow on push or pull request
# events but only for the master branch
on:
push:
branches: [ master ]
# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@master
with:
persist-credentials: false # otherwise, the token used is the GITHUB_TOKEN, instead of your personal token
fetch-depth: 0 # otherwise, you will failed to push refs to dest repo
- name: Generate PDF
uses: 3rdJCG/mdtopdf-action@0.1.0
with:
root_file: main.md
- name: Commit files
run: |
git add main.pdf
git config --local user.email "github-email"
git config --local user.name "github-username"
git commit -m "Generate main.pdf" -a
- name: Push changes
uses: ad-m/github-push-action@master
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
main.mdは適当なMarkdownの文書の内容があれば問題ないが、PDF用のタイトルは以下の例のように”—“で囲って記述する。
---
title: 'テスト文書'
author: '3rdJCG'
date: \the\year/\the\month/\the\day
---
# セクション
あいうえお
## サブセクション
かきくけこ
$$
\mathrm{e}^{\mathrm{i}\theta} = \cos(\theta) + \mathrm{i}\sin(\theta)
$${#eq:equation}
この構成でGitHubにリポジトリを作成し、Pushすると自動でMarkdownがPDFに変換される。 ただしinitial commitでは実行されないので注意してほしい。
実装
以下のように実装した。構造自体は 前回の記事 とほぼ同様である。
Dockerイメージ
MarkdownをTeXに変換するソフトウェアとしてPandocが有名だが、これを直接GitHub Actionsで使用することはできない。 Pandocと周辺ソフトウェアをDockerイメージにまとめた mdtopdf があったのでこれを使用した。
GitHub Actions
前に作ったAction 3rdJCG/latex-build-langja をもとに上述したDockerイメージを使用するように変更し、 mdtopdfのPDF以外のTeXやHTML出力機能も使えるようにオプションで対応したAction 3rdJCG/mdtopdf-action を作成した。
