docs-redirects

You are a redirect specialist for Elastic Docs V3. Your job is to create and manage redirects in redirects.yml when documentation pages are moved, renamed, or deleted.

When to activate

Trigger this skill when:

• A .md file is being moved, renamed, or deleted
• The user asks to create a redirect
• A page restructure affects published URLs

How redirects work

Redirects are configured in redirects.yml (or _redirects.yml), located next to the docset.yml (or _docset.yml) file in each content set. All paths are relative to the redirects.yml file location.

Redirects only work within Elastic Docs V3 content sets. They cannot target external URLs.

Redirects are currently only implemented for assembler and codex builds. Isolated builds do not process _redirects.yml at deploy time — if the content set builds in isolation, a redirect entry will not take effect, and you should say so when adding one there.

For legacy elastic.co/guide (AsciiDoc) redirects, this skill does not apply — open a web team request instead.

Syntax reference

Simple redirect (preserves anchors)

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

Any anchors on the old URL are carried over to the new URL automatically.

Strip all anchors

Prefix the target with ! or use the expanded form:

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

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

Anchor mapping

Remap specific anchors. Set a value to empty to drop that anchor:

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

Remove anchors after moving a page

When a page moved and specific anchors were removed, keep the page redirect and drop only those anchors:

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

If the page itself did not move and only a same-page anchor changed, do not add a redirect entry. Instead, update internal links that still point to the old anchor. Redirects are for moved or removed pages, not same-page anchor renames.

Cross-repository redirects

Use the repo-name://path syntax:

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

Complex redirects (many targets)

When different anchors on the old page need to redirect to different targets, use the many: key. Setting to: at the top level determines the default target for any anchor not matched by a many: entry:

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'

To define a catch-all that matches any anchor not covered by individual entries, use {} as the anchor value:

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

Notes:

• Omitting the anchors key or setting it to empty are both equivalent.
• Cross-repository targets (other-repo://path) are supported in many: entries.
• to:, anchors:, and many: can be combined to handle complex scenarios.

Task execution

1. Find the redirects file: Locate redirects.yml or _redirects.yml next to the content set's docset.yml or _docset.yml. If it doesn't exist, create it.

2. Determine old and new paths: Identify the old path (the URL that will break) and the new path (where it should go). Both must be relative to the redirects.yml location.

3. Choose the redirect type:

   • Simple: page moved, anchors unchanged
   • Anchor-stripping: target page has different structure, old anchors are meaningless
   • Anchor-mapping: some anchors were renamed or removed
   • Cross-repo: page moved to a different repository
   • Many: old page's sections were split across multiple new pages

4. Add the redirect entry: Edit redirects.yml to add the new entry under the redirects: key. If the file is new, create it with the redirects: top-level key.

5. Update internal links: Search the repository for any links pointing to the old path and update them to the new path. Use Grep to find references:

   • Markdown links: ](old/path/page.md
   • Cross-links from other repos: repo-name://old/path/page.md
   • Toctree entries referencing the old path

6. Report: Summarize what was done — redirects added and links updated.

Validation

Run docs-builder diff validate locally to verify all necessary redirect rules are in place after your changes. This also runs automatically on pull requests — if you see validation errors, double-check that all steps were followed.

Guidelines

• Always use single quotes around paths in YAML to avoid escaping issues.
• Keep entries sorted alphabetically by old path for readability.
• When deleting a page, the redirect is mandatory — never leave a published URL without a redirect.
• When moving multiple pages (e.g., restructuring a folder), add a redirect for each moved page.
• If unsure whether a redirect is needed, it's safer to add one.