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.

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 on a page that still exists

When a page hasn't moved but specific anchors were removed, omit the to: field:

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

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

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.
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.
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
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.
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
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.

docs-redirects

When to activate