ドキュメントのバージョン管理#

versions を有効にすると、SSG はライブの docs ツリーを凍結スナップショットの横に置き、ヘッダーにバージョンドロップダウンを描けます。

機能は自分でオンにするまでオフです。既存サイトはそのままです。バージョン管理は ディスク上でコンテンツを複製します。過去のスナップショットディレクトリはビルド中に読むだけで、書き戻しません。

import { oxContent } from "@ox-content/vite-plugin";

export default {
  plugins: [
    oxContent({
      versions: {
        current: "3.0.0-alpha",
        entries: [
          {
            id: "3.0.0-alpha",
            label: "3.0.0-alpha",
            prefix: "",
            banner: "unreleased",
          },
          {
            id: "2.90.0",
            label: "2.90.0",
            prefix: "2.90",
            dir: "versions/2.90",
          },
        ],
      },
    }),
  ],
};

false または省略はプレフィックス、バナー、ドロップダウンをオフのままにします。true は Latest ラベルの現在エントリ 1 つでオンになります。オブジェクトを渡すと機能はオンになり、設定したフィールドだけ上書きします。

オプション	型	既定
`versions`	`boolean` / `VersionsOptions`	`false`
`current`	`string`	最初のエントリ、または `"current"`
`switcher`	`boolean`	`true`
`badge`	`boolean`	`true`
`entries`	`VersionEntry[]`	現在の `Latest` エントリ 1 つ

各エントリは次を設定できます。

フィールド	目的
`id`	`current` が参照する安定キー
`label`	ドロップダウン文言（HTML エスケープ）
`prefix`	`2.90` や `next` のような URL セグメント。空文字はサイトルート
`dir`	Vite ルートからの相対スナップショットディレクトリ。省略するとライブの `srcDir`
`banner`	`"unreleased"`、`"unmaintained"`、または省略

プレフィックス付きツリー上の検索は、ルートのインデックスではなく {prefix}/search-index.json を取ります。sitemap は、スナップショット側が自分のファイルを書かない限り、ライブツリーに限定されます。javascript:、data:、vbscript:、//、.. のプレフィックスやスナップショットパスは捨てます。

凍結スナップショットの中では、安全なサイト内サイドバーとヘッダーリンクはそのスナップショットのプレフィックスの下に留まります。生成サイドバーと手動サイドバー、入れ子項目、パーマリンク、frontmatter エイリアス、設定したリダイレクト、パンくずのルート、前へ / 次へリンクを含みます。ロケール解決が先に走るので、/2.90/ja/ からのリンクは、翻訳兄弟があれば 2.90 バージョンと ja ロケールの両方を保ちます。

サイドバーの行き先がスナップショットになければ、ox-content は黙ってライブ docs に戻さず、そのバージョンのルート（たとえば /2.90/）へリンクします。外部 URL、mailto:、ハッシュのみのリンク、安全でないスキーム、プロトコル相対 URL にはバージョンプレフィックスを付けません。ライブツリーは、今までのプレフィックスなしナビのままです。

git タグからスナップショットを作り直すには次です。

node tools/scripts/snapshot-docs-version.mjs --tag v2.90.0 --prefix 2.90

ドキュメントのバージョン管理#

関連#