Astro(Starlight)でMarkdown内にTypst数式を描画する環境構築 (rehype-typst)

Astro (Starlight) 環境において、Markdown または MDX の中で数式を記述する際、従来の LaTeX 構文ではなく Typst 構文を利用して描画するための環境構築手順をまとめた。

本サイトでも実際に利用している @myriaddreamin/rehype-typst と remark-math を使った構築方法を解説する。

1. パッケージのインストール

まずは数式を解釈・描画するために必要なライブラリをインストールする。Markdown内の数式ブロックをパースする remark-math と、それを Typst 構文として SVG にレンダリングする rehype-typst 関連のパッケージが必要である。

npm install remark-math @myriaddreamin/rehype-typst @myriaddreamin/typst-ts-node-compiler @myriaddreamin/typst-ts-renderer @myriaddreamin/typst.ts

2. astro.config.mjs の設定

インストールしたプラグインを Astro の Markdown 処理パイプラインに組み込む。astro.config.mjs を以下のように編集する。

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import remarkMath from 'remark-math';
import rehypeTypst from '@myriaddreamin/rehype-typst';

export default defineConfig({
  integrations: [
    starlight({
      // ... その他の設定 ...
      customCss: ['./src/styles/custom.css'], // 後述のCSS調整用
    }),
  ],
  markdown: {
    // MarkdownのパースにremarkMathを使用
    remarkPlugins: [remarkMath],
    // 描画にrehypeTypstを使用
    rehypePlugins: [rehypeTypst],
  }
});

この設定を行うことで、Markdown内で $a^2 + b^2 = c^2$ や $$ \sum_{i=1}^n i $$ のように記述した箇所が Typst として評価され、SVG に変換されるようになる。

3. CSSの調整（必須）

rehype-typst は数式を SVG 画像として埋め込むが、その際にHTML全体へ影響を与えかねないグローバルな <style>（具体的には svg { ... } などのルール）を出力してしまう問題がある。

これにより、AstroのIconやStarlightの標準アイコン（ハンバーガーメニューやSNSアイコンなど）が表示されなくなるという不具合が起きる。

これを防ぐため、astro.config.mjs で指定したカスタムCSS（ここでは src/styles/custom.css）に以下の記述を追加し、アイコンのスタイルを元の状態に強制的に戻す。

/* ======================================================== */
/* Typst                                                    */
/* ======================================================== */

/* 数式のベーススタイル */
svg.typst-doc {
  display: inline-block;
  max-width: 100%;
  height: auto;
  margin-bottom: 0rem;
  margin-top: 0rem;
}

/* displayスタイル（ブロック数式）の場合の余白調整 */
:not(p, li, strong) > svg.typst-doc {
  padding-top: 1rem;
}

/* ======================================================== */
/* rehype-typst 影響によるSVGアイコン消失問題の対処          */
/* ======================================================== */
/* rehype-typstが数式を画像にするときに一緒にビルドするHTML内のCSS（svg {...}）が原因。 */

.starlight-aside__icon,
svg[class^="astro-"],           /* AstroのIconコンポーネント用 */
svg.icon.label-icon,            /* StarlightのSNSアイコン等 */
svg.caret,                      /* テーマ選択アイコン等 */
svg[class^=" astro-"],          /* 目次の矢印アイコン等 */
starlight-menu-button svg {     /* スマホ版ハンバーガーメニュー */
  fill: currentColor;
}

これで、Starlight 本来のデザインを崩すことなく、数式だけを綺麗に Typst で描画できるようになる。

まとめ

Markdown内でTypst数式を利用するには、remark-math と rehype-typst プラグインを導入する。
rehype-typst のグローバルなSVGスタイル出力による副作用でシステムアイコンが消えるため、カスタムCSSでスタイルをリセットする必要がある。
この環境を構築することで、従来の MathJax や KaTeX（LaTeX構文）に比べてよりモダンでシンプルな記述で数式表現が可能になる。

他の記事を探す