コンテンツにスキップ

ADR-0042: 公開するスライドは、ビルドのときに静的な HTML にして /slides/<slug> に置き、記事には iframe で埋め込む

Status

承認

Context

運営者が作ったスライドを、サイトで公開し、記事に埋め込む。
公開するスライドの URL、ページ送りの作り方、記事への埋め込みの形、Markdown の配置先を決める必要がある。

Decision

1. Markdown の配置先と URL

運営者は、公開するスライドの Markdown を、apps/web/src/content/slides/<slug>.md に置く。
ビルドのときに、Node で marp-core を動かして静的な HTML にし、fukuemon.dev/slides/<slug> で公開する。

  • 記事の schema と分ける。スライドを追加するときに変えるファイルは、その Markdown の 1 枚である。
  • 公開するスライドのページには、トークンの CSS を入れる。
  • サイトの URL に、次の 1 つを足す。ADR-0030 の Decision 2 のほかの URL は変えない。
URL 中身
/slides/<slug> 運営者が公開するスライド

最初の公開では、スライドの一覧のページを作らない。
スライドには、記事の埋め込みと、スライドの URL から辿る。

2. ページ送り

ページ送りは、リンクと CSS の :target で作る。
JavaScript を無効にしても、前後に送れるようにするためである。

  • スライドごとに「前へ」「次へ」のリンクを置き、URL の #2 のような番号で、表示するスライドを決める。
  • JavaScript が有効なときは、矢印キーでも送れる。

3. 記事への埋め込み

記事には、スライドのページを <iframe> で埋め込む。
記事のページの CSS と、Marp の CSS を分けるためである。

Verification

端末、ブラウザ、バージョンは、ADR-0041 の Verification と同じである。

  • 運営者の Markdown を、Node のスクリプトで静的な HTML にした。4 枚の描画は 122 ミリ秒だった（最初の 1 回。ライブラリの読み込みを含まない）。
  • 出力のページは 33 KB で、トークンの CSS の 21 KB を含む。Marp の出力に、<script> は入らなかった。
  • リンクと :target と :has() で作ったページ送りで、JavaScript を無効にして、1 枚目から 2 枚目、3 枚目、2 枚目へ送れた（3 つのブラウザ）。
  • 記事にスライドのページを <iframe> で埋め込み、JavaScript を無効にしても、1 枚目が出て、iframe の中のリンクで送れた。
  • iframe の中のページは、OS の設定の明暗に従った。記事のページの data-theme は、iframe の中に届かなかった。
  • marp-cli の bespoke のテンプレートは、試していない。JavaScript なしで送れるかは未確認である。
  • COEP: require-corp を返す記事に、スライドの iframe を埋め込めるかは未確認である。
  • 全画面の表示と、スワイプでの操作は作っていない。

Considered Options

選択肢 強み 弱み
採用: 静的な HTML を /slides/<slug> に置き、ページ送りをリンクと :target で作り、記事には iframe で埋め込む JavaScript なしで、前後に送れる。依存は marp-core だけで、ビルドにブラウザが要らない。サイトのトークンで画面を作れる ページ送りの画面を、自分で作って保守する。全画面の表示と、スワイプでの操作は、別に作る
marp-cli の bespoke のテンプレートで HTML を作る ページ送り、進み具合のバー、タッチの操作が、最初から付く marp-cli の依存が増える。JavaScript なしで送れるかは未確認。画面の見た目を、サイトに合わせにくい
全てのスライドを、1 ページに縦に並べる 作るものが最も少ない。JavaScript も :has() も要らない ページを前後に送る操作が、スクロールになる
記事の形式に、スライドを足す スライドが、記事の一覧とシリーズに入る ADR-0030 は、埋め込むコンテンツを形式にしないと決めている
play.fukuemon.dev のエディタのページを、iframe で見せる 公開するスライドのページを作らない スライドを見るだけの訪問者も、エディタの JavaScript を読み込む。JavaScript なしで読めない
ビルドのときに、スライドの HTML を記事の中に展開する iframe が要らない Marp の CSS を、記事の CSS と分ける処理が要る。その処理は未確認
記事には、1 枚目の画像とリンクだけを置く 記事のページが軽い 記事の中で、スライドを送れない
Markdown を、記事のディレクトリの中か、記事の本文のフェンスに置く スライドを、記事と一緒に管理できる 記事の schema に、スライドの項目が入る。記事に埋め込まないスライドを公開できない

Consequences

Positive

  • 運営者は、Markdown の 1 枚を置くだけで、スライドを URL で公開できる。
  • 訪問者は、JavaScript を無効にしても、スライドを開いて前後に送れる。
  • スライドのページは、エディタの JavaScript を読み込まない。

Negative

  • サイトの URL の種類が 1 つ増える。ADR-0030 の URL の表だけを読むと、スライドの URL が分からない。
  • ページ送りの画面を、自分で作って保守する。
  • ページ送りは、CSS の :has() に依る。
  • 公開するスライドのページごとに、トークンの CSS（21 KB）が入る。
  • サイトにテーマを切り替える操作を置くことにしたときは、iframe の中のスライドに明暗を届ける仕組みが要る。