docs-redirects

Elastic Docs V3 のリダイレクトを専門に扱います。ドキュメントページの移動、名前変更、削除が行われたときに、redirects.yml のリダイレクトを作成、管理します。

有効にするタイミング

次の場合にこのスキルを有効にします。

• .md ファイルを移動、名前変更、削除するとき
• ユーザーがリダイレクトの作成を依頼したとき
• ページの再構成によって公開 URL に影響があるとき

リダイレクトの仕組み

リダイレクトは、各コンテンツセットの docset.yml（または _docset.yml）ファイルの隣にある redirects.yml（または _redirects.yml）で設定します。すべてのパスは redirects.yml ファイルの場所を基準とする相対パスです。

リダイレクトは Elastic Docs V3 のコンテンツセット内でのみ機能します。外部 URL を転送先に指定することはできません。

リダイレクトが現在実装されているのは、アセンブラーと codex のビルドのみです。独立したビルドでは、デプロイ時に _redirects.yml は処理されません。コンテンツセットが独立してビルドされる場合、リダイレクトエントリは反映されないため、その場合は追加時にその旨を伝えてください。

従来の elastic.co/guide（AsciiDoc）のリダイレクトには、このスキルは適用されません。代わりにWeb チームへのリクエストを作成してください。

構文リファレンス

シンプルなリダイレクト（アンカーを保持）

redirects:
  'old/path/page.md': 'new/path/page.md'

古い URL に含まれるアンカーは、自動的に新しい URL に引き継がれます。

すべてのアンカーを削除

転送先の先頭に ! を付けるか、展開形式を使用します。

redirects:
  # Short form
  'old-page.md': '!new-page.md'

  # Expanded form
  'old-page.md':
    to: 'new-page.md'
    anchors: '!'

アンカーのマッピング

特定のアンカーを別のアンカーに割り当てます。アンカーを削除するには、値を空にします。

redirects:
  'old-page.md':
    to: 'new-page.md'
    anchors:
      'old-anchor': 'new-anchor'
      'removed-anchor':

ページの移動後にアンカーを削除

ページを移動し、特定のアンカーを削除した場合は、ページのリダイレクトを維持し、該当するアンカーのみを削除します。

redirects:
  'existing-page.md':
    to: 'new-page.md'
    anchors:
      'removed-anchor':

ページ自体は移動せず、同じページ内のアンカーのみが変更された場合は、リダイレクトエントリを追加しないでください。代わりに、古いアンカーを参照する内部リンクを更新してください。リダイレクトは、移動または削除されたページに使用するものであり、同じページ内のアンカー名の変更には使用しません。

リポジトリをまたぐリダイレクト

repo-name://path 構文を使用します。

redirects:
  'old-page.md': 'other-repo://path/to/new-page.md'

複雑なリダイレクト（複数の転送先）

古いページの異なるアンカーをそれぞれ異なる転送先にリダイレクトするには、many: キーを使用します。トップレベルに to: を設定すると、many: エントリに一致しないアンカーのデフォルトの転送先になります。

redirects:
  # Default target stays on the same page; specific anchors redirect elsewhere
  'old-page.md':
    to: 'old-page.md'
    many:
      - to: 'target-two.md'
        anchors:
          'anchor-a': 'anchor-b'
      - to: 'target-three.md'
        anchors:
          'anchor-c':

  # Default target is a different page with anchors stripped
  'deleted-page.md':
    to: 'default-target.md'
    anchors: '!'
    many:
      - to: 'target-two.md'
        anchors:
          'anchor-a': 'anchor-b'
      - to: 'other-repo://path/to/new-page.md'
        anchors:
          'anchor-b': 'anchor-c'

個別のエントリで指定されていないすべてのアンカーに一致するキャッチオールを定義するには、アンカー値として {} を使用します。

redirects:
  'old-page.md':
    many:
      - to: 'specific-page.md'
        anchors:
          'section-one': 'new-section'
      - to: 'catch-all-page.md'
        anchors: {}

注意：

• anchors キーを省略する場合と、空に設定する場合は、どちらも同じ意味です。
• リポジトリをまたぐ転送先（other-repo://path）は、many: エントリでサポートされています。
• to:、anchors:、many: を組み合わせて、複雑なケースに対応できます。

タスクの実行

1. リダイレクトファイルを探す：コンテンツセットの docset.yml または _docset.yml の隣にある redirects.yml または _redirects.yml を探します。ファイルが存在しない場合は作成します。

2. 古いパスと新しいパスを特定する：古いパス（無効になる URL）と新しいパス（転送先）を特定します。どちらも redirects.yml の場所を基準とする相対パスでなければなりません。

3. リダイレクトの種類を選択する：

   • シンプル：ページを移動し、アンカーに変更がない
   • アンカー削除：転送先ページの構成が異なり、古いアンカーに意味がない
   • アンカーマッピング：一部のアンカーの名前が変更されたか、削除された
   • リポジトリ間：ページを別のリポジトリに移動した
   • 複数：古いページのセクションを複数の新しいページに分割した

4. リダイレクトエントリを追加する：redirects.yml を編集し、新しいエントリを redirects: キーの下に追加します。ファイルを新規作成する場合は、トップレベルキーとして redirects: を記述します。

5. 内部リンクを更新する：リポジトリ内で古いパスを参照するリンクを検索し、新しいパスに更新します。Grep を使用して参照を検索します。

   • Markdown リンク：](old/path/page.md
   • 他のリポジトリからのクロスリンク：repo-name://old/path/page.md
   • 古いパスを参照する Toctree エントリ

6. 報告する：実施した内容を要約します。追加したリダイレクトと更新したリンクを報告します。

検証

変更後に必要なリダイレクトルールがすべて設定されていることを確認するには、ローカルで docs-builder diff validate を実行してください。これはプルリクエストでも自動的に実行されます。検証エラーが表示された場合は、すべての手順に従ったかどうかを再確認してください。

ガイドライン

• エスケープの問題を避けるため、YAML ではパスを必ずシングルクォートで囲んでください。
• 読みやすさのため、エントリは古いパスのアルファベット順に並べてください。
• ページを削除する場合、リダイレクトは必須です。公開済みの URL をリダイレクトなしのままにしないでください。
• 複数のページを移動する場合（フォルダーの再構成など）、移動したページごとにリダイレクトを追加してください。
• リダイレクトが必要かどうかわからない場合は、追加しておくほうが安全です。