zfb
GitHub リポジトリ

検索したい単語を入力

いつでも検索バーを開ける

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

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

このページの内容

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

zfb は静的サイトエンジンです。pages/ をスキャンし、コンテンツコレクションを走査し、MDX パイプラインを実行し、TSX を評価し、paths()、getStaticProps()、prerender、contentType、headings のようなページモジュール export を読み取り、ファイルをディスクに書き出します。ここまでがエンジンです。

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

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

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

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

  1. フロントマター — .md、.mdx、.tsx のソースをまたぐ統一された契約。下流では 1 つの JSON 形状になります。

  2. コンテンツコレクション — 型付けされたマークダウンコンテンツのディレクトリで、ビルド時に走査されます。

  3. ビルド時コンテンツクエリブリッジ — ページから同期的な getCollection / getEntry 呼び出しを可能にする、決定論的な Rust→JS スナップショット。契約は安定しており、コンテンツコレクションに文書化されています。

  4. 動的ルート — paths() が [slug].tsx / [...slug].tsx ページとしてビルドする具体的な URL を列挙します。

  5. カスタムディレクティブ — Rust を書くことなく、コンテナ・リーフ・テキストの MDX ディレクティブを登録し、JSX コンポーネントにマッピングします。

  6. 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 ではなくフレームワークに属します。

小さな例: ページモジュールが head データを props として渡す

head タグとレイアウト合成はフレームワークの関心事です。zfb は export const meta というページモジュール契約を出荷していません。代わりに、エンジンのデータ読み込み export を使ってフレームワーク / レイアウトが必要とするデータを渡し、通常のコンポーネントコードで <head> をレンダリングしてください。

// pages/about.tsx
export function getStaticProps() {
  return {
    props: {
      title: "About",
      description: "Who we are.",
    },
  };
}

export default function AboutPage({ title, description }) {
  return (
    <html lang="en">
      <head>
        <title>{title}</title>
        <meta name="description" content={description} />
      </head>
      <body>
        <h2>{title}</h2>
      </body>
    </html>
  );
}

ここでエンジンが何をして何をしないかに注目してください。エンジンは getStaticProps() をパースし、その props でページコンポーネントを呼び出し、結果をレンダリングします。og:image を描画するかどうか、どのフォールバックを使うか、タイトルをどう整形するか、レイアウトコンポーネントをどこに置くか — これらはすべてフレームワークレベルの判断です。

オプトインの Markdown 拡張

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

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

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

次に見る場所

  • 各エンジンプリミティブについては、上記でリンクした各コンセプトページを参照してください。

  • Markdown 拡張カタログについては Markdown 機能 を参照してください。

  • ページモジュールの表面そのものについては、ページモジュールのエクスポート が、zfb が今日読み取る named export を文書化しています。

Revision History

作成更新