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)

yaml

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:

yaml

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:

yaml

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:

yaml

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:

yaml

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:

yaml

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:

yaml

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

NPX Install

Tags

SKILL.md Content

When to activate

How redirects work

Syntax reference

Simple redirect (preserves anchors)

Strip all anchors

Anchor mapping

Remove anchors after moving a page

Cross-repository redirects

Complex redirects (many targets)

Task execution

Validation

Guidelines