Markdown 機能
zfb の Markdown パイプラインが提供するすべての機能と設定面。Core パイプラインの挙動と opt-in 機能を含みます。
zfb の Markdown パイプラインは階層構造になっています。Core 機能の一群は エンジンのメイン Markdown パイプライン / config surface の中で動作し、見出しアンカー、 サーバーサイドのシンタックスハイライト、CJK フレンドリーな処理などを提供します。 Core の行には常時有効なものもあれば、トップレベルまたは markdown.* config knob として Core パイプラインに実装されているものもあります。下の表は、各 Core / Opt-in サーフェスの デフォルトと設定キーをすべて記載することを目指していますが、config スキーマから生成された ものではなく手作業で保守されているため、新しく追加された構文に追随できていない場合が あります。最新の挙動は、リンク先の機能ページやそれが対応する config 型で確認してください。
このページは全体の地図です。各機能には、使用例・設定キー・順序に関する 注意点をまとめた専用ページがあります。
依存グラフ
zfb-content — コア機能はここにある。常にコンパイルされる
└─ zfb-md-extras — オプトイン機能。コンパイルはされるが実行時にゲートされる
└─ zfb-md-ast — 共有 AST 型（MdastNode、HastNode、ビジター）zfb-md-ast クレートは MdastVisitor および HastVisitor トレイトと 共有ノード型を定義します。コアとオプトインの両方の機能がこれらの トレイトを実装します。
ティアの規約
Core —
zfb-contentまたはトップレベルの Markdown config surface に実装されています。Core は常に「設定不可」を意味するわけではありません。設定キーとデフォルトは表で確認してください。Opt-in — config で有効化されない限り無効です。opt-in feature entry の多くは
markdown.features.*配下にありますが、stripMdExtとmarkdown.hardBreaksは opt-in のトップレベルオプションです。
各機能ページでは、タイトル付近に Core または Opt-in のバッジが表示されます。
設定の形
import { defineConfig } from "zfb/config";
export default defineConfig({
stripMdExt: true,
markdown: {
hardBreaks: true,
features: {
mermaid: true,
directives: {
note: "Note",
tip: "Tip",
},
},
},
});Boolean shorthand は普遍ではありません。値の形に boolean を含む行でだけ使えます。codeEnrichment、tocExport、imageDimensions、linkValidation、transclude、headingIds のような object-only の行には object が必要です。未知のキーは config load 時に拒否されます。
機能マップ
| Feature | Tier | Config key | Value shape | Default / gating |
|---|---|---|---|---|
| GFM 構文 | Core | markdown.gfm | boolean | { strikethrough?: boolean; table?: boolean; autolinkLiteral?: boolean; taskListItem?: boolean; footnoteDefinition?: boolean } | 省略時は保守的なデフォルト（strikethrough / table / autolinkLiteral が on、残り 2 つは off）。true / false のショートハンドは 5 つすべてを切り替える。 |
| CJK フレンドリーな強調 | Core | markdown.cjkFriendly | boolean | true; opt out するには false。 |
| 見出しリンク | Core | markdown.features.headingIds | { strategy?: "flat" | "hierarchical" } | Plugin は常に有効。デフォルト strategy は "flat"。 |
| コードブロックのタイトル | Core | none | n/a | 常に有効。 |
| 外部リンク | Core | markdown.externalLinks | { target?: string; rel?: string[] } | 指定されない限り off。 |
| リンク解決 | Core | resolveMarkdownLinks | { enabled?: boolean; docsDir?: string; dirs?: { dir: string; routePrefix: string }[]; onBrokenLinks?: "warn" | "error" | "ignore" } | enabled: true でない限り off。 |
| .md 拡張子の除去 | Opt-in | stripMdExt | boolean | false; true のとき .md / .mdx を除去して / を付ける。 |
| ハード改行 | Opt-in | markdown.hardBreaks | boolean | false; true のとき soft line break が <br> になる。 |
| シンタックスハイライト | Core | codeHighlight | { theme?: string; themesDir?: string; themeLight?: string; themeDark?: string; mode?: "inline" | "class"; classPrefix?: string; roleClasses?: Partial<Record<CodeHighlightRole, string>>; defaultStylesheet?: boolean } | デフォルトの syntect テーマで有効（mode: "inline"）。mode: "class" はセマンティックな role class を出力する — 完全な形はリンク先ページを参照。 |
| ディレクティブレジストリ | Core primitive | markdown.features.directives or Rust API | Record<string, DirectiveSpec> | レジストリ visitor は指定されたときだけ実行。デフォルト名はゼロ。 |
| ディレクティブ | Opt-in | markdown.features.directives | Record<string, string | { component: string; kind?: "container" | "leaf" | "text"; titleFromLabel?: boolean }> | 省略時は off。{} は空のレジストリを配線する。 |
| Mermaid ダイアグラム | Opt-in | markdown.features.mermaid | boolean | {} | 省略または false で off。ブロックを <div class="mermaid"> としてマークする。 |
| 見出しマーカー TOC | Opt-in | markdown.features.headingMarkerToc | boolean | { heading?: string; maxDepth?: number } | 省略または false で off。 |
| GitHub アラート | Opt-in | markdown.features.githubAlerts | boolean | {} | 省略または false で off。 |
| 読了時間 | Opt-in | markdown.features.readingTime | boolean | { wpm?: number } | 省略または false で off。export const readingTimeMinutes を出力。 |
| コードブロックのエンリッチメント | Opt-in | markdown.features.codeEnrichment | { diffMarkers?: boolean; lineHighlight?: boolean; wordHighlight?: boolean } | 省略時は off。object form で有効化され、すべての subfeature はデフォルトで on。 |
| コードタブ | Opt-in | markdown.features.codeTabs | boolean | {} | 省略または false で off。 |
| ルビ注釈 | Opt-in | markdown.features.ruby | boolean | {} | 省略または false で off。 |
| TOC エクスポート | Opt-in | markdown.features.tocExport | { maxDepth?: number } | 省略時は off。デフォルト maxDepth は 3。 |
| 画像サイズ | Opt-in | markdown.features.imageDimensions | { skipRemote?: boolean } | 省略時は off。skipRemote のデフォルトは true。 |
| リンク検証 | Opt-in | markdown.features.linkValidation | { failOnBroken?: boolean } | 省略時は off。デフォルトは警告、failOnBroken: true でエラー。 |
| トランスクルージョン | Opt-in | markdown.features.transclude | { maxDepth?: number } | 省略時は off。デフォルト maxDepth は 5。 |
関連項目
設計思想 — レシピをオプトイン機能へ 昇格させるための「3 つの利用者」のしきい値。
Markdown パイプラインを拡張する — Rust ビジターを書いてエンジンに組み込む。
カスタムディレクティブ — Rust を書かずに 新しいディレクティブ名を登録する。
レシピ: 拡大可能な画像 — 削除された
imageEnlarge組み込み機能の代替を、imgコンポーネントの上書きで ユーザーランドで実現する。レシピ: Admonitions —
:::note、:::tipなどを最小限のコンポーネントスタブと CSS フックとともにdirectivesで登録する。