Ovellum v0.25.0
日本語
GitHub npm お問い合わせ
開く

最終更新

バージョン管理されたドキュメント#

メジャーバージョンを保守するライブラリは、ドキュメントもそれに合わせる必要があります。 v1 を読んでいる読者には、今の main の姿ではなく v1 の API が見えるべきです。 Ovellum はドキュメントをディレクトリでバージョン分けし — 各バージョンが独自の コンテンツサブツリーになります — トップバーにバージョンピッカーを追加します。これは オプトインです。バージョンなしのサイトには content/<id>/ フォルダは不要で、 これまでどおりに動作します。

有効にする#

site.versions でバージョンを宣言し、 各バージョンのコンテンツを content/<id>/ フォルダに移動します。

export default {
  site: {
    versions: [
      { id: 'v2', label: 'v2 (latest)', latest: true }, // / で配信
      { id: 'v1', label: 'v1' },                         // /v1/ で配信
    ],
  },
} satisfies OvellumUserConfig;

content/
  v2/                ← 最新、ルートで配信
    index.md
    guides/install.md
  v1/                ← /v1/ で配信
    index.md
    guides/install.md
  • id は URL セグメントであり、フォルダ名（content/v2/）でもあります。
  • label はピッカーに表示される名前です。デフォルトは id。
  • latest はプレフィックスなしのルート（/）で配信されるバージョンを示します。 指定できるのは最大 1 つで、なければ最初のエントリが採用されます。

最初のビルドで各サブツリーが読み込まれ、最新バージョンはルートに、その他はその id の 配下に出力されます。

dist/
  index.html                  ← v2 のホーム
  guides/install/index.html   ← v2
  v1/index.html               ← v1 のホーム
  v1/guides/install/index.html

バージョンピッカー#

2 つ以上のバージョンがあると、トップバーにピッカーが現れます（言語ピッカーがあれば その隣）。バージョンを切り替えると、読者は対象バージョンの同じページに移動し （/guides/install/ の v2 は /v1/guides/install/ へジャンプ）、そのページが存在 しない場合はそのバージョンのホームにフォールバックします。だからバージョン間で ページを追加・削除しても、リンク切れは生まれません。

新しいバージョンを切る#

バージョン管理は単なるフォルダなので、新しいメジャーのリリースはコピーと設定編集 だけです — そのコピーは ovellum snapshot がやってくれます:

npx ovellum snapshot 1.0

現在の最新コンテンツを content/1.0/ として凍結し、追加すべき site.versions エントリを表示します。（このコマンドが設定を編集することはありません — TypeScript の 設定は機械編集が安全にできないため、設定変更は常にあなたがレビューして行います。） まだ site.versions のないプロジェクトでは、一度きりの移行手順も表示します: バージョンを有効にすると、すべてのバージョンが独自のディレクトリを持つため、 作業中のコンテンツも content/<latest-id>/ へ移動します。

古いバージョンはただのコンテンツです — 編集しないことで凍結しても、パッチを当て続けても、 どちらでも構いません。

古いバージョンと検索エンジン#

最新でないバージョンは、意図して訪れる読者のためのもので、検索トラフィックの ためのものではありません — そのため最新でないすべてのページには自動的に:

  • トップバーの上にバナー — 「これは v1 のドキュメントで、最新バージョンでは ありません。[最新版に切り替える]」 — が付き、最新バージョンの同じページに リンクします（他のクロームと同じくローカライズされます）;
  • <meta name="robots" content="noindex"> が入り、
  • sitemap.xml から除外されます（最新バージョンだけが載ります）。

設定は不要で、site.versions から自動的に導かれます。最新バージョンは そのままです。

複数言語との併用#

バージョンは i18n と組み合わせられます。両方を設定すると、 ロケールは各バージョンの内側にネストします。

content/
  v2/
    en-US/docs/install.md   → /docs/install/
    ja/docs/install.md      → /ja/docs/install/
  v1/
    en-US/docs/install.md   → /v1/docs/install/
    ja/docs/install.md      → /v1/ja/docs/install/

言語ピッカーは現在のバージョン内でロケールを切り替え、バージョンピッカーは現在の ロケール内でバージョンを切り替えます。hreflang の alternate はバージョン内に 留まります。

バージョンごとに得られるもの#

各バージョンは一人前のサイトです。独自のサイドバーナビ、_meta.json の順序、 フロントマターを持ちます。ビルド成果物もバージョンごとに出力されます — RSS と llms.txt はバージョンごとに書き出され（最新は ルート、古いものはそのプレフィックス配下）、sitemap.xml には最新だけが 載ります（最新でないページは noindex になります — 上記を参照）。

このページを編集