Skip to content

Add a procedure for creating a redirect that passes CI checks #1893

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Sep 17, 2025
Merged

Add a procedure for creating a redirect that passes CI checks #1893

Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ee198db
Add a procedure for creating a redirect that passes CI checks
florent-leborgne Sep 16, 2025
e003860
Update docs/contribute/redirects.md
florent-leborgne Sep 17, 2025
4b949a1
Update docs/contribute/redirects.md
florent-leborgne Sep 17, 2025
6ac064a
Update docs/contribute/redirects.md
florent-leborgne Sep 17, 2025
f08b3f4
Update docs/contribute/redirects.md
florent-leborgne Sep 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions docs/contribute/redirects.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,29 @@ For API redirects, consult with the documentation engineering team on Slack (#el

For elastic.co/guide redirects, open a [web team request](http://ela.st/web-request).

## Add a redirect

To successfully implement a redirect:

1. Locate and open the `redirects.yml` file to edit.
- Each docs repository powered by Docs V3 can have its own `redirects.yml` file. You must only edit the one in the repository that you're moving or removing files from.
- It is at the same location as the `docset.yml` file. Depending on the repository, this is generally at the root or within the `/docs` folder of the repository.

:::{note}
It is possible that there is no `redirects.yml` file yet in some repositories. If that's the case, create it next to the repo's `docset.yml` file. Refer to [](#file-location).
:::

2. Edit the file. Refer to [](#syntax) to get details on the expected syntax.
- All paths must be relative to the `redirects.yml` file.
- You may need to adjust the syntax based on how you'd like to treat anchors within redirected files. Find examples in [](#syntax).

3. Fix all existing links to the moved or removed file within the repository where you're adding the redirect, by updating them to the new correct target, or by removing them if necessary. This is a best practice to keep our content healthy, and mandatory for your PR to pass CI checks.

4. Create a PR with all of the changes made through the previous steps.

CI checks run to validate the newly added redirect and the docs build.
In case of validation errors related the redirect, double check that your changes comply with all steps of this procedure. If the errors persist, ask @elastic/docs-engineering for assistance in your PR.

## Validation

Running `docs-builder diff validate` will give you feedback on whether all necessary redirect rules are in place after your changes. It will also run on pull requests.
Expand Down
Loading