タラバガニー設計局stalins.clubNOTE/notes/peitho-slide-tool
AIpeitho-slide-tool

peitho で資料を書く

Go Release Party 1.27 の発表資料は mizzy/peitho v1.22.1 (Rust製) で Markdown から 組んだ。完全な README がバイナリに同梱されているので、仕様の一次情報はそこ (Homebrew なら /opt/homebrew/Cellar/peitho/1.22.1/README.md)。

使えないもの

  • 引用 > と表 |---| は未対応。書くと error: unsupported construct 'blockquote' / 'table' でビルドが落ちる。使えるのは見出し・段落・リスト・ フェンスコード・画像・脚注のみ。取り消し線 ~~x~~ も未対応で、そのまま文字として 出力される。
  • コード言語タグに typescript / ts / text / toml / dockerfile などは 使えない。ビルドエラーになる。タグを外せば無タグのプレーン扱いになり通る。 使えるのは go bash sh zsh js javascript python py diff sql xml php makefile ruby rb c cpp java json yaml md markdown html css rust scala perl lua erb など。
  • include は v1.22.1 にバグがあり、include スライドの次のスライドが飲み込まれて 消える。1ファイル完結で書くのが無難。

回避策の核心: レイアウトを増やさずスロットを足す

引用と画像・mermaid が使えない問題は、「レイアウトを追加するしかない」と最初は 誤解した。error: no slot accepts image in layout 'title-body-code' を見ると そう読めるが、実際には既存レイアウトにスロットを足すだけで解決する。

<blockquote class="quote">
  <slot name="quote" accepts="blocks" arity="0..*"></slot>
</blockquote>
<figure class="diagram">
  <slot name="diagram" accepts="image" arity="0..1"></slot>
</figure>

流し込みは明示スロット記法で行う。::: の直後には空行が必須で、無いと content on the line after ':::' is attached to the fence で落ちる。

::: {slot=quote}

We do not anticipate that Go will ever add generic methods.

— Go FAQ

:::

ハマりどころ:

  • arity="0..1" だと引用が1ブロックしか入らない。引用本文と出典行で2段落になる ため slot 'quote' got 2 item(s) で落ちる。0..* にする必要がある。
  • blocks スロットが2つあっても、既存スライドの慣習マッピングは壊れない。 README の書き方だと全スライドで明示ルーティングが要るように読めるが、実際は 明示ルーティングしていない本文はそのまま body スロットに流れる。
  • スロットの並び順がそのまま描画順になる。引用を本文より前に見せたいなら、 レイアウト側で quote を body より上に書く。Markdown 上の記述順序では 決まらない。
  • 空スロットは空白ノードが残るため :empty セレクタが効かない。 .quote:not(:has(.slot-quote)) のような形で消す必要がある。
  • mermaid のノードラベルは ["..."] で囲めば [ をそのまま書ける。 &#91; のような実体参照を使うと A&[A[int]&] のように壊れて出る。

レイアウトを増やすときの罠

レイアウトが1つだけなら無条件でそれが使われる。2つ以上にすると型駆動 ディスパッチになり、あるスライドへのマッチが0個でも2個以上でもビルドエラーに なる。例えばタイトルのみの cover レイアウトを足すと、タイトルだけのスライドが cover と既存レイアウトの両方にマッチして落ちる。レイアウトを増やすなら <!-- {"layout":"..."} --> によるピン留めを前提に設計する必要がある。

その他

  • セクションを1つでも使うなら最初のスライドに必ず section マーカーが要り、 セクション時間の合計が front matter の time と一致しないとビルドエラーになる。
  • JSON でない HTML コメントは全部スピーカーノート扱いで dist/ には入らない。
  • peitho lint は headless Chrome ではみ出しと 24pt 未満の文字を警告し、 警告があると exit 1 になる (px × 0.75 = pt)。
  • README に載っていない機能として、コードの行強調がある。 ```go {2-3} は静的強調 (PDF にも焼き込まれる)、 ```go {1|2-3|4} は present 中に矢印キーで1グループずつ進むステップ強調。

日本語見出しの泣き別れには CSS の text-wrap: balance と word-break: auto-phrase の組み合わせが効いた。後者は Chrome 119+ で文節単位に折り返す。

この制約 (表が使えない、レイアウトは実質1枚) は、そのまま資料の書き方を規定した。 ジェネリクスメソッド (Go 1.27) の解説で 4象限や条件別の比較を出したくなっても、 スライド上では表にできないので箇条書きかコードブロックに落とすことになる。 調査内容の一覧は Go 1.27 ジェネリクスメソッド 調査ノート。

出典

Go Release Party 1.27 の発表資料リポジトリ memo.md §4。

🔗 リンクされているノート

▸ ノート一覧に戻る