Astro + Starlight で CeTZ を安定して動かす方法 (Typst 描画環境の構築)

数学的で美しい図表を Typst で描画したい場合、CeTZ は最も有力なライブラリである。しかし、Astro と Starlight を使用したドキュメントサイトでは、CeTZライブラリが簡単には使えない。最新版の WASM 依存やパス解決の仕様が原因で、ビルドエラーを引き起こすことが多い。そこで、生成AIを利用して強引にCeTZライブラリを使えるようにした。

パッチをあてた CeTZ のソースコードを GitHubのプロジェクトに置いたので、必要ならダウンロードしてほしい。

GitHub: astro-starlight-typst パッチ適用済みの CeTZ v0.3.2 ソースコードを公開している。ルートディレクトリのlibsフォルダを参照のこと。

クイック・サマリー

課題: CeTZ v0.5 以降の WASM プラグインがビルド時に実行できない。
- すべてのバージョンを試したわけではないので、CeTZ v0.4系はうまく行くかもしれない。
解決策: 純粋な Typst 実装である v0.3.2 をプロジェクト内の libs/cetz へコピーして使用する。
必須設定: astro.config.mjs で root: "." を指定し、絶対パスによるインポートを可能にする。

1. 安定版 CeTZ v0.3.2 を選ぶ理由

最新の CeTZ (v0.5.x) は WASM プラグインに依存しており、SSG (静的サイト生成) のビルドプロセスでエラーが発生しやすい。これに対し、v0.3.2 は純粋な Typst コードで構成されているため、環境を選ばず動作が安定している。ハッセ図や関数グラフなどの主要機能は v0.3.2 で十分に提供されている。

2. 導入手順

一から自分でライブラリを導入するには、以下の手順が必要である。

ライブラリのローカル配置 プロジェクトルートに libs/cetz フォルダを作成し、CeTZ のソースコードを配置する。パッケージマネージャ経由（@preview）での利用は、ビルド環境の制限により推奨されない。
パス置換パッチの適用 CeTZ 内部の #import 文を Astro のプロジェクトルートから解決できるよう、"/src/ を "/libs/cetz/src/ に全置換する。
依存関係のスタブ化 oxifmt 等のパッケージが利用できない場合、libs/cetz/src/oxifmt.typ に #let strfmt(fmt, ..args) = fmt というスタブを作成し、ビルドを安定させる。
astro.config.mjs の設定 astro-typst に root: "." を設定し、/libs/... パスを有効化する。

3. 実装例：ハッセ図の描画

FAQ: CeTZ 導入のよくある質問

Q1: CeTZ v0.5 で「Plugin not found」が出るのはなぜか？

A1: 最新版が WASM を使用しており、Astro のビルド環境（Vite）が Typst 内からの WASM 呼び出しを適切に処理できないためである。v0.3.2 を使用することで回避できる。

Q2: 座標解決で Panic が発生する

A2: Typst のバージョンアップによる型判定の変更が原因である。coordinate.typ 内で type(x) を repr() と組み合わせて文字列比較するように修正することで解決する。

結論

きれいな数学図式を描画するには、TypstだけでなくCeTZのようなライブラリの導入が欠かせない。異なるシステムを組み合わせるときは、「枯れたバージョンをローカルで管理し、環境に合わせたパッチを当てる」戦略が最も効果的である。

他の記事を探す