Hugo+Academic+reveal.jsでMarkdownスライドを作成

4 min読了の目安(約3700字TECH技術記事

TL;DR

  • Hugo + Academicテーマ (+ reveal.js) を利用して、Markdownでスライドを書いてサイトに公開する方法
  • Hugo + Academicテーマでサイトを構築する手順はこの記事のスコープ外 (そのうち書くかも)
  • (身も蓋もないが) Hugo + Academicテーマのサイトを持っている人が対象なので、それ以外のスライドをMarkdownで書きたい人は、reveal.jsを直接使うと良い (参照1, 参照2)

公開したスライドの中身(=強化学習の論文調査)についての記事はこちら

https://zenn.dev/ymd_h/articles/35d88f7d739651

1. はじめに

1.1 Hugo

静的サイトジェネレータのHugoを利用してブログプロジェクトサイトを構築しています。HugoはGoで書かれており、Markdownからの変換が速いとしばしば言われています。(私も、CIで毎回生成し直していますが、特に生成時間が気になったことはありません。)

1.2 Academicテーマ

Hugo はテーマを設定することで、サイトの見た目の変更や機能の拡張を行うことができ、私のブログはAcademicテーマ(次のv5からwowchemyに名称変更予定) を利用しています。

CMSのような使い勝手を提供したり簡単にNetlifyと連携したりと、ユーザービリティを意識した(元々は)研究者向けのテーマです。一方で、素のHugoからかなり拡張しているので、他のテーマとの互換性はあまり高くないと感じています。そのため、Hugo+Academicで、別の新たなエコシステムを構築しているイメージです。(もちろん、ShortcodesなどのHugoの素の機能を活用できます。)

余談ですが、私はそういった便利機能はほとんど無視して、設定ファイルを自分で書いてGitLab CIでビルドして、GitLab Pages (日本語記事)で公開しています。 (今回の記事のスコープ外ですが、そのうち別の記事として書くかも)

1.3 reveal.js

reveal.js はHTMLやMarkdownで書いたコンテンツを(パワーポイントのような)スライド形式のWebページとして表示するライブラリです。

Academicテーマは、このreveal.jsを組み込んでおり、 Markdownでのスライド執筆がコンテンツ作りの一部に位置づけられています。

ただし、?print-pdf によるPDF出力はHugoのサイト上では現在動いていません。 require('system') と書いてあってブラウザ上ではエラーになっています。

2. スライドの書き方

(Academicテーマが設定済みとします。)

2.1 雛形作成

hugo new slides/スライド名 を実行すると content/slides/スライド名/index.md に雛形が作成されます。 (theme/academic/archetype/slides/index.md に大本の雛形が提供されています。)

2.2 スライドの作成

基本的にはMarkdownですが、いくつか reveal.jsのスライド専用の記法があります。

  • ---: スライドのページ間の区切り (横方向にページの追加)
  • >>>: 縦方向にページを追加

Academicテーマを利用していることによる固有の書き方は以下のexampleに記載があります。

https://github.com/wowchemy/starter-academic/blob/master/exampleSite/content/slides/example/index.md
  • Shortcodes {{% fragment %}} でスライド内に部品が順番に出現する動きを加えられる
  • Shortcodes {{< speaker_note >}} でスピーカーノートを追加
  • Shortcodes {{< slide background-image="/(画像パス).jpg" >}} で背景画像追加
  • Shortcodes {{< slide background-color="#0000FF" >}} で背景色設定
  • CSSは assets/css/reveal_custom.css に記載する

2.3 手元での確認

サイトのルートディレクトリで、hugo server を実行すると、ローカルにサーバーが立ち上がるので、localhost:1313/(サイト名)/slides/(スライド名)/ にアクセスすると確認できる。

Hugoは基本的には手元のファイルの変更に追従して自動でサイトを更新してくれます。(Shortcodesなど一部の機能は起動中に更新するとうまくサイト表示ができなくてエラーになるので、その際はサーバーをCtr+Cなどで一旦停止して再起動すれば良い。)

3. スライドのサイト内への埋め込み

こちらの記事を参考にして、ShortcodesでiframeをHugoのサイトの中に埋め込みます。

layouts/shortcodes/SlideInclusion.html
<iframe src="{{.Get 0}}" width="1000" height="600" frameborder="0" allowfullscreen="allowfullscreen" allow="geolocation *; microphone *; camera *; midi *; encrypted-media *"></iframe>

あとはこのShortcodesを用いて {{< SlideInclusion "https://(サイトURL)/slides/(スライド名)/" >}} と記載すれば作成したスライドをHugoのサイト内に埋め込める。

もし、他のShortcodesと組合せて思ったとおりに表示されなければこちらの記事もどうぞ。

https://zenn.dev/ymd_h/articles/6a8b173d55512c

Hugo+Academicテーマにおいて、スライドを埋め込むのに適したページのArchtypesはtalk (v5以降はevent)かなぁと思っています。