エンジンとフレームワーク

作成 2026年6月24日Takeshi Takatsudo

zfb はエンジンであり、将来の zudo-doc-v2 のようなフレームワークはそのプリミティブの上に乗る

このページの内容

zfb の対象範囲が、エンジンプリミティブ（zfb が責任を持つ 6 つの要素）と、エンジンの外側にあるフレームワークの関心事（サイドバー、検索、ブログの規約、テーマ）にどう分割されているかを解説します。

zfb は静的サイトエンジンです。pages/ をスキャンし、コンテンツコレクションを走査し、MDX パイプラインを実行し、TSX を評価し、ページのメタ情報をレイアウトに通し、ファイルをディスクに書き出します。ここまでがエンジンです。

フレームワーク — 将来の zudo-doc-v2 や、ブログキット、あるいは誰かが下流で公開するもの — は、こうしたエンジンプリミティブの寄せ集めを、完成したサイト体験へと仕上げるものです。サイドバーの生成、検索、バージョン管理 UI、テーマ操作、ブログのルーティング、i18n ルーティング。これらはすべてフレームワークの関心事です。

このページが存在するのは、両者を分ける境界線が重要な役割を担っているからです。ある機能がどちら側にあるかを知ることは、それをどこで探し、どこで拡張し、zfb 自身が答えを用意していないときにプロジェクトとして何を担うべきかを教えてくれます。

6 つのエンジンプリミティブ

zfb v1 がコミットするのは、ちょうど 6 つのプリミティブです。フレームワークはこれらの上に構築されます。zfb の他のどの部分も、公開された表面契約には含まれません。

フロントマター — .md、.mdx、.tsx のソースをまたぐ統一された契約。下流では 1 つの JSON 形状になります。
コンテンツコレクション — 型付けされたマークダウンコンテンツのディレクトリで、ビルド時に走査されます。
ビルド時コンテンツクエリブリッジ — ページから同期的な getCollection / getEntry 呼び出しを可能にする、決定論的な Rust→JS スナップショット。契約は安定しており、コンテンツコレクションに文書化されています。
動的ルート — paths() が [slug].tsx / [...slug].tsx ページとしてビルドする具体的な URL を列挙します。
カスタムディレクティブ — Rust を書くことなく、コンテナ・リーフ・テキストの MDX ディレクティブを登録し、JSX コンポーネントにマッピングします。
HTML 以外のページ — pages/sitemap.xml.tsx、pages/llms.txt.tsx、pages/feed.rss.tsx など。独自の拡張子と Content-Type を持つ第一級の出力です。

ここまでがエンジンです。安定し、名前が付けられ、文書化されています。

zfb が行わないこと

これらはフレームワークの関心事です。zfb は土台を提供します。それを組み立てるのは、あなた（または依存先のフレームワーク）です。

サイドバー / ナビゲーションツリーの生成。
検索インデックスの構築（Pagefind、Lunr など）。
ブログの規約（タグページ、アーカイブ、RSS フィードの配線、ページネーション）。
i18n ルーティング — /... をミラーする /ja/...、ロケールネゴシエーション。
テーマ操作（ライト / ダーク / ディム、デザイントークン、カラーパレット UI）。
バージョン管理 UI — マルチバージョンドキュメント、バージョンドロップダウン。
レイアウトコンポーネント — ヘッダー、フッター、目次、カードグリッド。
サイトレベルのクロム — スキップリンク、フォーカス管理、トップへスクロール。

原則はこうです。「zfb 上に構築された 2 つのフレームワークが、これをそれぞれ異なるやり方で行うか？」の答えが「はい」なら、それは zfb ではなくフレームワークに属します。

小さな例: レイアウトがエンジンの `meta` を消費する

エンジンはページのメタデータを PageMeta を通して受け渡します。レイアウト — これはエンジンのコードではなくあなたのコードです — は meta を読み取り、それを <head> に投影します。次は小さなデフォルトレイアウトです。

// layouts/default.tsx
export default function DefaultLayout({ meta, children }) {
  const og = meta?.openGraph ?? {};
  return (
    <html lang={meta?.lang ?? "en"}>
      <head>
        <title>{meta?.title ?? "Untitled"}</title>
        {meta?.description && (
          <meta name="description" content={meta.description} />
        )}
        {og.image && <meta property="og:image" content={og.image} />}
      </head>
      <body>{children}</body>
    </html>
  );
}

ページ側はメタを宣言するだけです。

// pages/about.tsx
export const meta = {
  title: "About",
  description: "Who we are.",
  openGraph: { image: "/og/about.png" },
};

export default function AboutPage() {
  return <h2>About us</h2>;
}

ここでエンジンが何をして何をしないかに注目してください。エンジンは meta をパースし、レイアウトを解決し、ページの出力をそれでラップします。og:image を描画するかどうか、どのフォールバックを使うか、タイトルをどう整形するか — これらはすべてフレームワークレベルの判断です。zfb は「型付けされた PageMeta をレイアウトに渡す」ところで止まります。

オプトインの Markdown 拡張

すべての Markdown 機能がプリミティブなわけではありません。zfb-md-extras クレートは、オプトインで利用できる機能のカタログ — Mermaid 図、GitHub スタイルのアラート、読了時間の挿入、トランスクルージョンなど — を提供します。これらはフレームワーク色が強いものです。ブログフレームワークなら読了時間やルビ注釈を有効にするかもしれませんし、技術リファレンスフレームワークならリンク検証やコードブロックのエンリッチメントを求めるかもしれません。どちらのセットも普遍ではありません。

これらを Core に組み込むのではなくオプトイン（zfb.config.ts でプロジェクトごとに有効化）に保つことで、zfb は特定のフレームワークの意見をエンジンに焼き付けることを避けます。6 つのエンジンプリミティブは公開契約の全体であり続け、拡張カタログは追加的で独立して切り替え可能です。

全リストは Markdown 機能を参照してください。

次に見る場所

各エンジンプリミティブについては、上記でリンクした各コンセプトページを参照してください。
Markdown 拡張カタログについては Markdown 機能を参照してください。
head/meta の表面そのものについては、meta エクスポートが、どのフィールドが第一級でどう extra が残りを運ぶかを文書化しています。