Markdown 機能

作成 2026年6月24日Takeshi Takatsudo

zfb の Markdown パイプラインが提供するすべての機能 — コア（常時有効）とオプトイン（zfb.config.ts で有効化）。

zfb の Markdown パイプラインは階層構造になっています。コア機能の一群はすべてのコンテンツコレクションに対して無条件で動作し、見出しアンカー、サーバーサイドのシンタックスハイライト、CJK フレンドリーな強調などを提供します。その上に、オプトイン機能のカタログがあり、zfb.config.ts の markdown.features.* で一つずつ有効化できます。

このページは全体の地図です。各機能には、使用例・設定キー・順序に関する注意点をまとめた専用ページがあります。

依存グラフ

zfb-content          — コア機能はここにある。常にコンパイルされる
  └─ zfb-md-extras   — オプトイン機能。コンパイルはされるが実行時にゲートされる
       └─ zfb-md-ast — 共有 AST 型（MdastNode、HastNode、ビジター）

zfb-md-ast クレートは MdastVisitor および HastVisitor トレイトと共有ノード型を定義します。コアとオプトインの両方の機能がこれらのトレイトを実装します。

ティアの規約

コア — すべてのビルドで有効。設定キーはなし。zfb-content に存在する。
オプトイン — デフォルトでは無効。zfb.config.ts の markdown.features.* で有効化する。zfb-md-extras に存在する。

各機能ページでは、タイトル付近に Core または Opt-in のバッジが表示されます。

オプトイン機能を有効化する

zfb.config.ts

import { defineConfig } from "zfb/config";

export default defineConfig({
  markdown: {
    features: {
      mermaid: true,
      directives: {
        note: "Note",
        tip: "Tip",
      },
    },
  },
});

true（デフォルトを使用）または設定オブジェクト（特定のオプションを上書き）を渡します。キーを省略するとその機能はオフになり、余分なバイトは一切出力されません。

コア機能

これらの常時有効なプラグインは、zfb-content のデフォルトパイプラインの一部として同梱されています。

CJK フレンドリーな強調 — CJK の表意文字やかなに隣接する太字／斜体を再トークン化する。
見出しリンク — すべての見出しにスラッグ化した id 属性と自己参照アンカーリンクを付与する。
コードブロックのタイトル — title="…" からフェンス付きコードブロックの上にファイル名ラベルを描画する。
外部リンク — 外部リンクに target と rel 属性を付与する（設定可能）。
リンク解決 — コンテンツのソースマップを使って内部リンクの参照先を書き換える。
.md 拡張子の除去 — 内部リンクの href から .md／.mdx の接尾辞を取り除く。
シンタックスハイライト — syntect によるサーバーサイドハイライト。常時有効でテーマは設定可能。
ディレクティブレジストリ — :::name／::name／:name のディレクティブ構文を JSX コンポーネントへマッピングする。

オプトイン機能

それぞれ markdown.features.* で有効化します。すべて zfb-md-extras に存在します。

ディレクティブ — :::name／::name／:name のディレクティブ構文を独自の JSX コンポーネントにマッピングして登録する（デフォルトはゼロ。語彙はあなたが用意する）。
Mermaid ダイアグラム — フェンス付きコードブロックから Mermaid のフローチャートを描画する。
見出しマーカー TOC — 指定した見出しの後に目次を自動挿入する。
GitHub アラート — > [!NOTE]／> [!WARNING] の引用ブロックをスタイル付きコンポーネントとして描画する。
読了時間 — 推定読了時間を計算してフロントマターに注入する。
GitHub オートリンク — GitHub の issue／PR／コミット参照（#123、org/repo#456、abc1234）を自動的にリンクする。
コードブロックのエンリッチメント — フェンス付きコードブロックに diff マーカーと行単位のハイライトを追加する。
コードタブ — 連続するフェンス付きコードブロックをタブ切り替え式にまとめる。
ルビ注釈 — {これは}^{これ}（キャレット、推奨）または {漢字|かんじ}（パイプ、レガシーエイリアス）構文を HTML の <ruby> 要素として描画する。
TOC エクスポート — 構造化された見出しツリーをコンパイル済みの JSX モジュールにエクスポートし、フレームワーク側で描画できるようにする。
画像サイズ — 実際のファイルから <img> 要素に width と height 属性を注入する。
リンク検証 — デフォルトでは壊れた内部リンクを警告する。failOnBroken: true でビルドエラーにする。
トランスクルージョン — :::include ディレクティブを使って別ファイルの内容をインライン展開する。

Markdown 機能

依存グラフ

ティアの規約

オプトイン機能を有効化する

コア機能

オプトイン機能

関連項目

Revision History

AI Assistant