シンタックスハイライト

syntect によるサーバーサイドのシンタックスハイライト。常時有効でテーマは設定可能。

SyntectPlugin は、ビルド時にサーバーサイドのシンタックスハイライトを実行します。常に有効です。Markdown 内のすべてのフェンス付きコードブロックは、 syntect — Sublime Text 互換の文法を使う Rust ライブラリ — によってハイライトされ、色注釈付きの HTML が出力に焼き込まれます。ハイライトのために JavaScript がブラウザへ送られることはありません。

テーマの設定

デフォルトのテーマは "base16-ocean.dark" です。zfb.config.ts で変更します:

zfb.config.ts

export default {
  codeHighlight: {
    theme: "Solarized (light)",
  },
};

カスタムの .tmTheme ファイルや、補助的なクライアントサイドのパターンについては、以下の専用ガイドで解説しています。

ライト / ダークのデュアルテーマ

theme を 1 つ指定する代わりに、themeLight と themeDark の両方を設定すると、各ブロックを 2 回ハイライトし、トークンごとの色を CSS カスタムプロパティとして出力します。これにより、描画後にページのライト / ダークモードに応じてアクティブな色が選ばれます。JavaScript は不要です。

zfb.config.ts

export default {
  codeHighlight: {
    themeLight: "InspiredGitHub",
    themeDark: "base16-ocean.dark",
  },
};

themeLight と themeDark は必ずセットで指定する必要があり、theme とは排他です。<pre> には class="syntect-dual" が付与され、利用側は 1 つの light-dark() CSS ルールで色を解決します。これらは Shiki ではなく syntect のテーマ名です。出力される markup と CSS ルールについては、専用ガイドを参照してください。

出力モード

トークンを着色する方法は 3 つあり、codeHighlight.mode とテーマ関連フィールドで選択します。

シングルテーマのインライン（デフォルト） — mode: "inline" に単一の theme。トークンごとの色が style="color:…" に焼き込まれます。自己完結した HTML です。
デュアルテーマのインライン — themeLight + themeDark（mode は "inline" のまま）。トークンごとに --shiki-light / --shiki-dark カスタムプロパティが出力され、light-dark() CSS ルールで解決されます。
クラスモード（推奨） — mode: "class"。各トークンに意味的なロールクラス（hi-kw、…）が付き、再テーマ可能な --zfb-hi-* カスタムプロパティで着色され、色は焼き込まれません。ガイドのクラスモードの節を参照してください。

mode はテーマ関連フィールドと排他です。mode: "class" を theme / themeLight / themeDark / themesDir のいずれかと同時に指定するとビルドエラーになります。

詳細なドキュメント

テーマ名、カスタム .tmTheme の読み込み、クラスモードのロールトークン、クライアントサイドの補助的なハイライト、ビルド後のカスタム文法パターンについては、シンタックスハイライトを参照してください。

順序に関する注意

SyntectPlugin は hast フェーズで、CodeTitlePlugin、MermaidPlugin、その他すべてのコードブロックビジターの後、最後に実行されます。各 <pre><code> 要素を生の HTML フラグメントに置き換えるため、構造化された <pre> を読み取る必要があるプラグインは、これより前に実行されなければなりません。