Markdown 機能
zfb が提供する組み込みおよびオプトイン Markdown パイプライン機能。
zfb の Markdown パイプラインは、常に有効な Core(組み込み) 機能と、zfb.config.ts の markdown.features で個別に有効化する Opt-in(オプトイン) 機能を提供します。
Core 機能
以下の 7 機能は常に有効です。設定は不要です。
| 機能 | 説明 |
|---|---|
| CJK Friendly | 中国語・日本語・韓国語(CJK)の文章に対して、スペーシングと改行処理を改善します。 |
| Heading Links | h2 以上の見出しにアンカーリンクを追加し、ページ内の直接リンクを可能にします。 |
| Code Title | コードブロックに title="…" を設定すると、ファイル名や見出しバーを表示します。 |
| Resolve Links | 相対パスの .mdx/.md リンクをクリーンなドキュメント URL に解決します。 |
| Strip .md Extension | 出力される内部リンクの href から .md/.mdx 拡張子を除去します。 |
| Syntax Highlighting | アクティブなカラースキームに対応するビルド時セマンティッククラスハイライト。 |
| Directives Registry | 汎用的な :::name ディレクティブエンジン — ディレクティブ構文を JSX コンポーネントにマッピングします。アドモニションのボキャブラリはレシピとして別途登録されます。 |
Opt-in 機能
以下の 14 機能は zfb エンジンレベルでは opt-in(オプトイン)です — 明示的に設定しない限り無効で、多くは markdown.features.* 配下のキーで設定します(External Links と Image Enlarge は別の形のキーを使います)。ただし、このショーケース自体は markdown を直接設定していません。zudoDoc({...}) プリセットが下表の markdown.features.* エントリの大半をあらかじめ有効化しています — プリセットの正確なデフォルト値は各機能のページを参照してください。素の defineConfig({ markdown: { features: {...} } }) は zudoDoc() を完全にバイパスし、プリセットが配線する残りすべて(コレクション、Chrome、コードハイライトなど)を失わせるため、常に zudoDoc({...}) から始めてその markdown ブロックを拡張してください。
| 機能 | 設定キー | 説明 |
|---|---|---|
| External Links | markdown.externalLinks | 有効化すると外部リンクに target/rel を付与します。デフォルトでは無効 — 有効/無効にかかわらず、本文中のリンクに自動的な視覚インジケーターは付与されません。 |
| Admonitions Preset | directives | directives マップでアドモニションのボキャブラリ(note/tip/warning/danger/info/caution/details)を登録します。 |
| Mermaid | mermaid | ```mermaid フェンスをクライアントサイドの Mermaid ライブラリで図として描画します。 |
| Image Enlarge | settings.imageEnlarge | クリックで拡大できる <figure> に画像をラップします。ユーザーランド設定 — 組み込みの markdown.features キーは next.18 で削除されました。 |
| Heading Marker TOC | headingMarkerToc | 各見出しにアンカーマーカーを付与し、TOC アイランドにデータを提供します。 |
| GitHub Alerts | githubAlerts | > [!NOTE]/[!TIP]/[!WARNING]/[!IMPORTANT]/[!CAUTION] ブロック引用をアドモニションマークアップに変換します。 |
| Reading Time | readingTime | 推定読了時間を計算し、ページレベルのメタデータとして公開します。 |
| Code Enrichment | codeEnrichment | ハイライト済みのコードブロックに diff/行/単語ハイライト装飾を追加します。タイトルバーは別の常時有効な Core 機能です(Code Title 参照)。コピー/折り返しボタンは、この機能の有効・無効にかかわらず、すべてのコードブロックに追加されます。 |
| Code Tabs | codeTabs | :::code-group ディレクティブを <CodeGroup> 経由でタブ付きコードパネルとして描画します。 |
| Ruby | ruby | ルビ注釈サポートを追加します({base}^{ruby} 構文)。 |
| TOC Export | tocExport | ページの目次を export const toc 名前付きエクスポートとして出力します。 |
| Image Dimensions | imageDimensions | ビルド時にディスクのメタデータから画像に width/height 属性を付与します。 |
| Link Validation | linkValidation | ビルド時に内部リンクを検証し、壊れた参照に警告(またはエラー)を出します。 |
| Transclude | transclude | :::include{file="…"} で別ファイルの内容を埋め込みます。zudo-doc では無効(transclude レンダラー未配線)。 |
その他のパイプライン設定
zfb にはトップレベルの markdown 設定として markdown.gfm(GitHub Flavored Markdown の各構文をきめ細かく切り替える)と markdown.hardBreaks(ソフト改行をすべて <br> に変換する)も存在します。どちらも上記の Core/Opt-in の一覧には含まれていません。markdown.hardBreaks はこのプロジェクトの zfb.config.ts で設定されていませんが、zudoDoc({...}) プリセットはデフォルトで markdown.gfm: { taskListItem: true, footnoteDefinition: true } を設定しているため、GFM のタスクリストとフットノートは [ ] / [^1] というリテラルなテキストではなく実際にレンダリングされます。