バージョン管理

バージョン管理CLIを使用して、`docs`ディレクトリの最新コンテンツに基づいて新しいドキュメントバージョンを作成できます。その特定のドキュメントセットは、`docs`ディレクトリのドキュメントが進化し続けても、保存されアクセス可能になります。

警告

ドキュメントのバージョン管理を開始する前に、よく検討してください。コントリビューターが改善に協力するのが難しくなる可能性があります！

ほとんどの場合、バージョン管理はビルド時間を増加させ、コードベースを複雑にするだけなので、必要ありません。バージョン管理は、**トラフィックが多く、バージョン間のドキュメントの変更が速いWebサイトに最適です**。ドキュメントがめったに変更されない場合は、ドキュメントにバージョン管理を追加しないでください。

バージョン管理の仕組みを理解し、ニーズに合っているかどうかを確認するには、以下をお読みください。

概要

一般的なバージョン管理されたドキュメントサイトは次のようになります。

website
├── sidebars.json        # sidebar for the current docs version
├── docs                 # docs directory for the current docs version
│   ├── foo
│   │   └── bar.md       # https://mysite.com/docs/next/foo/bar
│   └── hello.md         # https://mysite.com/docs/next/hello
├── versions.json        # file to indicate what versions are available
├── versioned_docs
│   ├── version-1.1.0
│   │   ├── foo
│   │   │   └── bar.md   # https://mysite.com/docs/foo/bar
│   │   └── hello.md
│   └── version-1.0.0
│       ├── foo
│       │   └── bar.md   # https://mysite.com/docs/1.0.0/foo/bar
│       └── hello.md
├── versioned_sidebars
│   ├── version-1.1.0-sidebars.json
│   └── version-1.0.0-sidebars.json
├── docusaurus.config.js
└── package.json

`versions.json`ファイルは、バージョン名のリストで、最新のものから順に並べられています。

次の表は、バージョン管理されたファイルがそのバージョンと生成されたURLにどのようにマッピングされるかを説明しています。

パス	バージョン	URL
versioned_docs/version-1.0.0/hello.md	1.0.0	/docs/1.0.0/hello
versioned_docs/version-1.1.0/hello.md	1.1.0 (最新)	/docs/hello
docs/hello.md	カレント	/docs/next/hello

ヒント

`docs`ディレクトリ内のファイルは、`current`ドキュメントバージョンに属します。

デフォルトでは、`current`ドキュメントバージョンは`Next`としてラベル付けされ、`/docs/next/*`でホストされますが、プロジェクトのリリースライフサイクルに合わせて完全に設定可能です。

用語

ここで使用する用語に注意してください。

現在のバージョン

`./docs`フォルダにあるバージョン。

最新バージョン/最終バージョン

ドキュメントナビゲーションバーの項目にデフォルトで表示されるバージョン。通常、パスは`/docs`です。

現在のバージョンは**ファイルシステムの場所**によって定義されますが、最新バージョンは**ナビゲーションの動作**によって定義されます。これらは同じバージョンである場合とそうでない場合があります！（そして、上記の表に示されているように、デフォルト設定では、それらを異なるものとして扱います。現在のバージョンは`/docs/next`、最新バージョンは`/docs`です。）

チュートリアル

新しいバージョンのタグ付け

1. まず、現在のドキュメントバージョン（`./docs`ディレクトリ）が固定できる状態になっていることを確認してください。
2. 新しいバージョン番号を入力します。

npm

npm run docusaurus docs:version 1.1.0

Yarn

yarn docusaurus docs:version 1.1.0

pnpm

pnpm run docusaurus docs:version 1.1.0

新しいバージョンをタグ付けすると、ドキュメントバージョン管理メカニズムは次のようになります。

• `docs/`フォルダの内容全体を新しい`versioned_docs/version-[versionName]/`フォルダにコピーします。
• 現在のサイドバー設定（存在する場合）に基づいて、バージョン管理されたサイドバーファイルを作成します。これは`versioned_sidebars/version-[versionName]-sidebars.json`として保存されます。
• 新しいバージョン番号を`versions.json`に追加します。

新しいドキュメントの作成

1. 新しいファイルを対応するバージョンフォルダに配置します。
2. バージョン番号に従って、対応するサイドバーファイルに新しいファイルへの参照を含めます。

現在のバージョンの構造

# The new file.
docs/new.md

# Edit the corresponding sidebar file.
sidebars.js

古いバージョンの構造

# The new file.
versioned_docs/version-1.0.0/new.md

# Edit the corresponding sidebar file.
versioned_sidebars/version-1.0.0-sidebars.json

ヒント

バージョン管理されたサイドバーファイルは、標準のサイドバーファイルと同様に、指定されたバージョンのコンテンツルートからの相対パスです。したがって、上記の例では、バージョン管理されたサイドバーファイルは次のようになります。

{
  "sidebar": [
    {
      "type": "autogenerated",
      "dirName": "."
    }
  ]
}

または、手動サイドバーの場合は次のようになります。

{
  "sidebar": [
    {
      "type": "doc",
      "id": "new",
      "label": "New"
    }
  ]
}

既存のバージョンの更新

`versioned_docs/`の各ディレクトリは公開時に特定のルートを表すため、複数のドキュメントバージョンを同時に更新できます。

1. 任意のファイルを編集します。
2. 変更をコミットしてプッシュします。
3. バージョンに公開されます。

例：`versioned_docs/version-2.6/`のファイルを 변경하면、バージョン`2.6`のドキュメントにのみ影響します。

既存のバージョンの削除

バージョンを削除/削除することもできます。

1. `versions.json`からバージョンを削除します。

例

[
  "2.0.0",
  "1.9.0",
- "1.8.0"
]

2. バージョン管理されたドキュメントディレクトリを削除します。例：`versioned_docs/version-1.8.0`。
3. バージョン管理されたサイドバーファイルを削除します。例：`versioned_sidebars/version-1.8.0-sidebars.json`。

バージョン管理動作の設定

「現在の」バージョンは、`./docs`フォルダのバージョン名です。バージョン管理にはさまざまな方法がありますが、2つの非常に一般的なパターンは次のとおりです。

• v1をリリースし、すぐにv2（ドキュメントを含む）の作業を開始します。この場合、**現在のバージョン**はv2で、`./docs`ソースフォルダにあり、`example.com/docs/next`で参照できます。**最新バージョン**はv1で、`./versioned_docs/version-1`ソースフォルダにあり、`example.com/docs`でほとんどのユーザーが参照します。
• v1をリリースし、v2について検討する前にしばらくの間メンテナンスします。この場合、v2ドキュメントはまだ存在しないため、**現在のバージョン**と**最新バージョン**はどちらもv1を指します！

Docusaurusのデフォルトは、最初のユースケースでうまく機能します。現在のバージョンを「next」としてラベル付けし、公開しないことも選択できます。

**2番目のユースケースの場合**：v1をリリースし、すぐにv2に取り組む予定がない場合は、v1をバージョン管理し、2つのフォルダ（`./docs` + `./versioned_docs/version-1.0.0`）でドキュメントを保守する代わりに、現在のバージョンにパスとラベルを付けて、カットバージョンであるかのように「見せかける」ことを検討してください。

docusaurus.config.js

export default {
  presets: [
    '@docusaurus/preset-classic',
    docs: {
      lastVersion: 'current',
      versions: {
        current: {
          label: '1.0.0',
          path: '1.0.0',
        },
      },
    },
  ],
};

`./docs`のドキュメントは、`/docs/next`ではなく`/docs/1.0.0`で提供され、`1.0.0`はナビゲーションバーのドロップダウンにリンクするデフォルトバージョンになり、単一の`./docs`フォルダのみを保守する必要があります。

バージョン管理の動作をカスタマイズするためのプラグインオプションを提供しています。

• `disableVersioning`：バージョンが存在する場合でも、バージョン管理を明示的に無効にします。これにより、サイトには現在のバージョンのみが含まれます。
• `includeCurrentVersion`：ドキュメントの現在のバージョン（`./docs`フォルダ）を含めます。
  • **ヒント**：現在のバージョンが作業中で、公開準備ができていない場合はオフにします。
• `lastVersion`：「最新バージョン」（`/docs`ルート）がどのバージョンを参照するかを設定します。
  • **ヒント**：`lastVersion： 'current'`は、現在のバージョンが常にパッチ適用およびリリースされるメジャーバージョンを参照する場合に意味があります。最新バージョンの実際のルートベースパスとラベルは設定可能です。
• `onlyIncludeVersions`：デプロイする`versions.json`のバージョンサブセットを定義します。
  • **ヒント**：起動とビルド時間を改善するために、開発とデプロイプレビューでは2〜3バージョンに制限します。
• `versions`：バージョンメタデータの辞書。各バージョンについて、以下をカスタマイズできます。
  • `label`：バージョンドロップダウンとバナーに表示されるラベル。
  • path: このバージョンのルートベースパス。デフォルトでは、最新バージョンは /、現在のバージョンは /next です。
  • banner: 'none'、'unreleased'、'unmaintained' のいずれか。すべてのドキュメントページの上部に何が表示されるかを決定します。最新バージョンより上のバージョンは「unreleased（未リリース）」、下のバージョンは「unmaintained（メンテナンスされていない）」となります。
  • badge: そのバージョンのドキュメントの上部に、バージョン名を示すバッジを表示します。
  • className: そのバージョンのドキュメントページの <html> 要素にカスタム className を追加します。

詳細はドキュメントプラグインの設定をご覧ください。

ナビゲーションバーの項目

バージョン付きルートを気にすることなく、ナビゲーションをすばやく設定できるよう、いくつかのナビゲーションバー項目を提供しています。

• doc: ドキュメントへのリンク。
• docSidebar: サイドバーの最初の項目へのリンク。
• docsVersion: 現在表示されているバージョンのメインドキュメントへのリンク。
• docsVersionDropdown: 利用可能なすべてのバージョンを含むドロップダウン。

これらのリンクはすべて、以下の順序でリンク先の適切なバージョンを探します。

1. アクティブバージョン: ユーザーが現在閲覧しているバージョン（このドキュメントプラグインによって提供されているページにいる場合）。ドキュメントページにいない場合は、次のバージョンにフォールバックします。
2. 優先バージョン: ユーザーが最後に表示したバージョン。履歴がない場合は、次のバージョンにフォールバックします。
3. 最新バージョン: lastVersion オプションで設定された、ナビゲート先のデフォルトバージョン。

推奨事項

必要な場合にのみドキュメントのバージョン管理を行う

たとえば、npmパッケージ foo のドキュメントを作成していて、現在バージョン1.0.0だとします。その後、軽微なバグ修正のパッチバージョンをリリースし、現在は1.0.1です。

新しいドキュメントバージョン1.0.1を作成する必要がありますか？ **おそらく必要ありません**。セマンティックバージョニングによれば、1.0.1と1.0.0のドキュメントは、新機能がないため異なるべきではありません！新しいバージョンを作成しても、不要な重複ファイルが作成されるだけです。

バージョンの数を少なく保つ

経験則として、バージョンの数を10未満に保つようにしてください。誰も読まなくなった古いバージョンのドキュメントが **非常に多く** になる可能性があります。たとえば、Jest は現在バージョン 27.4 ですが、最低 25.X の最新ドキュメントバージョンのみをいくつかメンテナンスしています。少なく保ちましょう 😊

古いバージョンをアーカイブする

Jamstackプロバイダー（例：Netlify）にサイトをデプロイする場合、プロバイダーは各本番ビルドを不変のURLの下にスナップショットとして保存します。再構築されないアーカイブバージョンを、これらの不変のURLへの外部リンクとして含めることができます。JestのWebサイトとDocusaurusのWebサイトはどちらも、このようなパターンを使用して、アクティブに構築されるバージョンの数を少なくしています。

ドキュメント内では絶対インポートを使用する

ドキュメント内では相対パスインポートを使用しないでください。バージョンを作成すると、パスが機能しなくなるためです（ネストレベルが異なるなど）。website ディレクトリを指す、Docusaurusによって提供される @site エイリアスを利用できます。例：

- import Foo from '../src/components/Foo';
+ import Foo from '@site/src/components/Foo';

ファイルパスでドキュメントをリンクする

.md 拡張子付きの相対ファイルパスで他のドキュメントを参照することで、Docusaurusはビルド中にそれらを実際のURLパスに書き換えることができます。ファイルは対応する正しいバージョンにリンクされます。

The [@hello](hello.mdx#paginate) document is great!

See the [Tutorial](../getting-started/tutorial.mdx) for more info.

グローバルまたはバージョン管理された併置アセット

画像やファイルなどのアセットをバージョンごとにするか、バージョン間で共有するかを決定する必要があります。

アセットをバージョン管理する必要がある場合は、ドキュメントバージョンに配置し、相対パスを使用します。

![img alt](./myImage.png)

[download this file](./file.pdf)

アセットがグローバルな場合は、/static に配置し、絶対パスを使用します。

![img alt](/myImage.png)

[download this file](/file.pdf)