From ee198dba003a2ff09b2acdc7b7de11bc46892c4b Mon Sep 17 00:00:00 2001 From: Florent Le Borgne Date: Tue, 16 Sep 2025 18:51:44 +0200 Subject: [PATCH 1/5] Add a procedure for creating a redirect that passes CI checks --- docs/contribute/redirects.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/contribute/redirects.md b/docs/contribute/redirects.md index e3a205313..300deeda3 100644 --- a/docs/contribute/redirects.md +++ b/docs/contribute/redirects.md @@ -16,6 +16,27 @@ 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, reach out to the docs-engineering team. + ## 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. From e0038604f092573c83b4d802b8042798620b2aba Mon Sep 17 00:00:00 2001 From: florent-leborgne Date: Wed, 17 Sep 2025 09:10:49 +0200 Subject: [PATCH 2/5] Update docs/contribute/redirects.md --- docs/contribute/redirects.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/contribute/redirects.md b/docs/contribute/redirects.md index 300deeda3..2fb501e17 100644 --- a/docs/contribute/redirects.md +++ b/docs/contribute/redirects.md @@ -34,8 +34,10 @@ To successfully implement a redirect: 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, reach out to the docs-engineering team. +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 From 4b949a129b99a8f719dda2ee069a6ba3eaf75828 Mon Sep 17 00:00:00 2001 From: florent-leborgne Date: Wed, 17 Sep 2025 09:13:22 +0200 Subject: [PATCH 3/5] Update docs/contribute/redirects.md --- docs/contribute/redirects.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contribute/redirects.md b/docs/contribute/redirects.md index 2fb501e17..66591bfe8 100644 --- a/docs/contribute/redirects.md +++ b/docs/contribute/redirects.md @@ -37,7 +37,7 @@ To successfully implement a redirect: 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. +In case of validation errors related the redirect, double check that your changes comply with all steps of this procedure. If the errors persist after a writer reviewed the PR, ask @elastic/docs-engineering for assistance. ## Validation From 6ac064aca0ef6d92fe56fc37068eb716d11924a2 Mon Sep 17 00:00:00 2001 From: florent-leborgne Date: Wed, 17 Sep 2025 12:01:14 +0200 Subject: [PATCH 4/5] Update docs/contribute/redirects.md Co-authored-by: Liam Thompson --- docs/contribute/redirects.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contribute/redirects.md b/docs/contribute/redirects.md index 66591bfe8..e536ed534 100644 --- a/docs/contribute/redirects.md +++ b/docs/contribute/redirects.md @@ -25,7 +25,7 @@ To successfully implement a redirect: - 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). + Some repositories might not yet have a `redirects.yml` file. In this case, create one 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. From f08b3f4d610cbdd9bc6c49eb0549ac407ddfb41c Mon Sep 17 00:00:00 2001 From: florent-leborgne Date: Wed, 17 Sep 2025 12:01:30 +0200 Subject: [PATCH 5/5] Update docs/contribute/redirects.md Co-authored-by: Liam Thompson --- docs/contribute/redirects.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contribute/redirects.md b/docs/contribute/redirects.md index e536ed534..022e03b99 100644 --- a/docs/contribute/redirects.md +++ b/docs/contribute/redirects.md @@ -37,7 +37,7 @@ To successfully implement a redirect: 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 after a writer reviewed the PR, ask @elastic/docs-engineering for assistance. +If you get validation errors about the redirect, double check that your changes follow all the steps in this procedure. If the errors persist after a writer reviewed the PR, ask @elastic/docs-engineering for assistance. ## Validation