【GitHub Actions & Marp-CLI】進捗報告用スライドを速攻で作る
見やすいからタイトルに【】を付けることが多かったけど、 バズりたいだけのブログに見える なんとなくダサいので外そうかなぁ
1. Marp とは
週例ミーティングや勉強会など、なにかとスライドに成果をまとめて発表する機会が多い今日この頃。 てきとうに見やすいスライドを作りたいけど、Adobe や PowerPoint でじっくりコトコト煮詰めるほどの時間はかけたくないよ~というそこのあなた、是非 Marp の門を叩きましょう。
Marp とは、Markdown の書式からスライドを捻出してくれるエコシステム1のことです。 Markdown to Slide なツールはいくつか存在しますが、Marp の強みは以下の機能をすべて備えていること。
- Based on CommonMark
- Built-in themes and CSS theming
- :star: Directives and extended syntax
- :star: Export to HTML, PDF, and PowerPoint
- :star: Marp family: The official toolset
- Pluggable architecture
- Fully open-source
エクスポート形式が多岐にわたることやシンタックスハイライトの記法を備えていることはかなり嬉しいところ。 特に HTML 形式での出力はかなり機能が充実しており、PDF では機能しない mp4 や GIF も埋め込める他、なんとプレゼンテーションモードも備えているので、どこかにデプロイしておけばそのまま発表が出来る(しかもコメントアウト箇所がノートになる。強すぎ)。
2. Marp CLI のススメ
先の章であげた機能群の中でもう一つ、Marp family: The official toolset の特徴も嬉しいところ。オープンソースなこともあり、本家だけでなく Marpit や Marp for VSCode2 など派生プロジェクトの開発も活発である。
今回はその中でも Marp CLI を紹介する。
Marp CLI はその名の通り Marp のエクスポートを切り出した CLI ツールである。npm で公開されているので npx @marp-team/marp-cli
で使用可能である。便利。
その一方、
"Do you hate to install Node and Chrome locally?"
な人々もいるだろう(?) そのような人のため、Marp はなんと Docker image も公開している。神~
Marp-CLI on Docker の使い方
とは言え docker の使い方でいくつか躓いたところがあるので以下ポイントをまとめる。
ポイント 1:オプションの問題
Marp-CLI は高機能がゆえオプションがたくさんある。 typo や大文字小文字、フラグの指定忘れに注意。意外と時間を溶かした。
ポイント 2:ファイルパーミッションの問題
docker あるあるの問題。
Marp-CLI on Docker は変換対象のファイルが /home/marp/app/
に置かれる必要があるようで -v "$(pwd):/home/marp/app/"
によりボリュームをマウントしている。
しかし、Docker 経由でファイルを作成することによりホスト OS 側からファイルパーミッションエラーが起きることがある。これはホストユーザとコンテナ内ユーザのユーザ ID が異なることが起因しているため、コンテナを動かす際に揃えてやる必要がある。
幸い公式から既に解決法が提示されており、-e MARP_USER="$(id -u):$(id -g)"
オプションをつければ良いとのこと。-u $(id -u $USER)
でもいい気がするけど検証してないです。
- 参考
ポイント 3:フォントの問題
PDF 変換時は適切にフォントを指定しないと、文字化けや簡体字っぽくなることがある。これは docker オプションで -e LANG="ja_JP.UTF-8"
とした上で、markdown ファイル内の Front-matter で次のようにフォントを指定してやればよい。
style: | @import url('https://fonts.googleapis.com/css2?family=Noto+Sans+JP&display=swap'); section { font-family: 'Noto Sans JP', serif; }
3. GitHub Actions で PDF 生成の自動化
PDF 生成は Marp for VSCode で十分なのだが、他端末で共有するときや教授に見せる時にわざわざ Google Drive にアップロードしてノート PC でダウンロードして共有ドライブにアップロードして……という動作が面倒だった。ということで PDF へのエクスポートは GitHub Actions に任せ、Artifactとして一時保存しておくのが楽やろ~と思い、作った。
レポジトリは こちら。
生成された PDF ファイルは、workflow の結果 を見れば Artifacts
という項目にアップロードされている。クリックすればそのまま zip ファイルとしてダウンロードされるので便利。また保存期間もレポジトリの設定から編集できるので、各自調整してほしい(デフォルトでは 90days かな)。
[2021/04/20 更新] PDF のデプロイ先を、ncipollo/release-action を用いて Artifacts
から Releases
に変更しました。これによりファイル単位ではなく、Releaseのタグによってバージョン管理が可能となります。
基本的に前章で述べた注意点に気をつければこのまま使えるハズ。良かったら fork したり star つけたりしてください。
4. ToDo
パブリックリポジトリでは無制限で GitHub Actions が利用可能ですが、プロベートレポジトリでは 2000 min / month
に制限されています。そのため Docker images は都度リモートから pull するのではなくローカルにキャッシュしておきたいところ。できたらまたブログ書くかぁ。