末尾スラッシュポリシー

zfbがビルド時とランタイムで末尾スラッシュの適用をどのように分担するかについての解説。

概要

zudo-docは「常に末尾スラッシュあり」のURLポリシーを採用しています。すべてのページは末尾が / で終わるパスに配置されます。例えば /docs/getting-started ではなく /docs/getting-started/ です。

zfbは静的サイトビルダーのみであり、サーバーサイドのミドルウェアレイヤーはありません。そのため、適用は異なる担当者を持つ2つの関心事に明確に分割されます。

ビルド時 — zfb / url-normalizerの担当

静的ビルド中に出力されるすべてのURLは / で終わる必要があります。これは @takazudo/zudo-doc/url-normalizer の buildUrl() によって強制されます：

import { buildUrl } from "@takazudo/zudo-doc/url-normalizer";

// paths()の実装やインテグレーションで:
const url = buildUrl("docs", slug);          // "/docs/my-slug/"
const root = buildUrl();                      // "/"
const localized = buildUrl("ja", "docs", slug); // "/ja/docs/my-slug/"

buildUrl() は主要なヘルパーです。パスセグメントを結合し、冗長なスラッシュを除去し、結果を /<joined>/ でラップします。以下の箇所で使用されています：

• pages/sitemap.xml.tsx — <loc> エントリの生成。

• コレクションスラッグをルートパスにマップするzfbの paths() エクスポート。

• インテグレーションレベルのURL出力（llms.txt、claude-resourcesなど）。

外部データからパス名が届き、末尾スラッシュがあるかどうか不明な場合のために、補助ヘルパー normalizePathname() も用意されています：

import { normalizePathname } from "@takazudo/zudo-doc/url-normalizer";

const canonical = normalizePathname(rawPathname); // 末尾スラッシュがない場合は追加

スキップルール

normalizePathname() とその内部の shouldSkipNormalization() は、以下のスキップルールを適用します：

ランタイム — デプロイホストの担当

訪問者が末尾スラッシュなしで https://example.com/docs/guide と入力した場合、リクエストをインターセプトするフレームワークのコードはありません。静的ファイルはすでにデプロイされています。デプロイホストがリダイレクトを発行する責任を持ちます。

Cloudflare Pages

public/_redirects に以下のルールを追加します。ページ固有のリダイレクトルールより前に記述する必要があります（Cloudflare Pagesはルールを上から順に評価し、最初にマッチしたルールで停止します）：

# 末尾スラッシュなしのURLを正規形にリダイレクトする。
/:splat  /:splat/  301

Cloudflare Workers Static Assets

zudo-docは現在、Cloudflare PagesではなくCloudflare Workersにデプロイされ（wrangler.toml）、ビルド済みの dist/ をWorkersの静的アセットレイヤーを通じて配信します。静的ビルドはすでに末尾スラッシュのディレクトリ構造（dist/docs/getting-started/index.html）を出力しているため、Workersのアセットレイヤーは各正規 /<route>/ URLをビルド済みの index.html から直接配信します。

そのため、Pagesセクションで説明している手動の public/_redirects ルールはWorkersでは配信されません。これはPages → Workersへの移行（zudolab/zudo-doc#1691）で廃止されました。関連する wrangler.toml の設定は以下のとおりです：

[assets]
directory = "./dist"
not_found_handling = "404-page"   # マッチしないGETに対して dist/404.html を配信
run_worker_first = false          # アセットレイヤーがワーカーより先に参照される

その他のホスト

まとめ

この分割により、各関心事が適切な場所に置かれ、問題が発生した際にどのレイヤーが担当しているかを容易に把握できます。