何を行ったのか
LT会や勉強会などの軽いプレゼンを行うときに役立つ次のようなフローを整備しました。
- Marpを用いて、Markdownでプレゼンのスライド(pdf)を作成
- GitHub Actionsを用いて自動でPDFに変換
masterのスライドをBespokeのHTML形式に変換してGitHub Pagesで公開
何が便利なのか
Marpのメリット
MarpはMarkdown形式で箇条書き主体のプレゼン用スライドを作成できるツールです。VSCode拡張機能が公開されているので、基本的にそれを用いて作業しています。
- Markdownで記述できるので、細かいレイアウトに気を取られない
- 基本的に箇条書きで、px単位の調整をしなくて良い
- CSSでカスタムテーマを記述できるので、デザインに統一感が生まれ、見やすい
- GitHubと相性が良く、プルリクを受けることもできる
自動PDF変換のメリット
Marpで作成したスライドは基本的にPDFで出力するのですが、それを自動化することで次のようなメリットがあります。
- 常にPDFというプレビュー可能なファイルがリモートにある
- 環境依存の問題、具体的にはフォントの問題を解決できる
- (参加者が)ダウンロードできる
GitHub Pages上での公開のメリット
MarpのスライドはHTML形式でも出力が可能で、PDFよりもリッチな機能を備えています。
- 発表本番に自分のPCを使わなくても、ブラウザさえあれば、環境に依存せず表示できる
- 発表者用画面があり、時間や次のスライドが表示される
- 箇条書きに簡単なアニメーションをつけられる
作業手順
ローカルでMarpを使う
前に述べたとおり、MarpをVSCodeで使うための拡張機能Marp for VSCodeが公開されているので、これを使います。この拡張機能は、Marpのmdファイルをpreviewしたときに通常のpreviewではなく、スライドのような見た目で表示されます。また、ローカルでPDF変換を行うこともできます。
すべてローカルで、スライドを作成してプレゼンするだけなら、これだけで十分です。特にハマるポイントもないと思います。
GitHub ActionsでMarpを使う
こちらはハマるポイントが多いので、実際に動いているrepositoryを見てもらえると、分かりやすいかと思います。(スライドの内容についても間違っている所があればぜひプルリクください！ )
MarpのCLIであるmarp-cliにはDocker imageが用意されているので、それを使うことにします。このCLIを利用して、MarkdownファイルをPDFやHTML(Bespoke)に変換できます。
時間を費やした問題は2つで、ファイルパスの問題とフォントの問題です。
まず、ファイルパスの問題についてです。変換対象のファイルはDockerコンテナ内の /home/marp/app/ に置かれる必要があり、そのためにサンプルではvolumeをマウントしています。しかし、GitHub Actionsではworkspaceがコンテナ内の /github/workspace にマウントされるため、/github/workspacesをカレントディレクトリにしたいという気持ちがあります。実はDockerfile内で WORKDIR が設定されているため、Actionsのyamlの argsで --workdir /github/workspace を渡すなどして、WORKDIRを変更してあげると良いです。
次に、フォントの問題です。PDF変換時には適切にフォントを設定しないと、文字化けしたり、漢字が日本語の漢字ではなく中国語っぽい漢字になってしまったりします(cjk問題)。ここでいう「設定」とは単にCSSで指定するだけでなく、変換を行う環境、すなわち、Dockerコンテナ内に日本語のフォントを入れる必要があります。これは、Dockerfileに手を加える必要があったので、元のDockerイメージをベースにして改変した新しいDockerfileを作成し、それをactionとして用いることにしました。実際に、どのようにしたかはこちらのDockerfileを見ていただければと思います。
それ以外は特に問題なく作業を終えました。PDFについてはActionsのartifactに保存、HTMLについてはmasterへのpushをtriggerにmarp-cliで変換したものをGitHub Pagesにて公開といった感じです。
実際に動いている様子
最後に、実際にこのフローにより生成されたPDFやHTMLを載せておきます。
軽いスライドを効率的に作りたいときにMarpはとても便利です。自動変換/公開フローについても一度作ってしまえば使い回せるので、スライド発表・公開の準備がだいぶ楽になりました。