Update aliases documentation with 'Brunch and learn' feedback (#390)

* Update aliases documentation with 'Brunch and learn' feedback - Update advice to say that you must add an alias when a page is move. - Update advice to say that you should add a comment explaining relative aliases. - Visually restructure examples for improved readability. Signed-off-by: Jack Baldry <[email protected]> * Fix front matter Signed-off-by: Jack Baldry <[email protected]> * Rewrite the example to focus on the value of `.` and `..` and use a table for concrete redirects Signed-off-by: Jack Baldry <[email protected]> * Provide better explanation of why absolute redirects should be avoided * Prettier Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --------- Signed-off-by: Jack Baldry <[email protected]> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
grafana · Nov 30, 2023 · af9264f · af9264f
1 parent a097799
commit af9264f
Showing 1 changed file with 42 additions and 22 deletions.
diff --git a/docs/sources/write/front-matter/index.md b/docs/sources/write/front-matter/index.md
@@ -48,12 +48,13 @@ The following headings describe what each element does and provides guidelines f
 ### Aliases
 
 Use `aliases` to create redirects from the previous URL to the new URL when a page changes or moves.
-As a best practice, when you rename or move files, you should create an alias with a reference to the previous URL path to create a redirect from the old URL to the new URL.
+
+When you rename or move files, you must create an alias with a reference to the previous URL path to create a redirect from the old URL to the new URL.
 In some cases, for example when you have deleted content or split a file into multiple topics, it may not be possible to create an alias for the moved content.
 
 ### Example
 
-The following example file `intended-url.md` contains the alias `/original-url` within its YAML front matter:
+The following Markdown front matter snippet defines an alias `/original-url/`:
 
 ```markdown
 ---
@@ -68,38 +69,57 @@ The correct way to use aliases depends on whether the project is versioned or no
 
 #### Versioned projects
 
-Do not include an `aliases` entry that refers to the initial published website directory.
-The version in the URL path can cause undesirable redirects, such as a redirect from latest content to an old version.
-Aliases must be relative and not absolute paths so that old versions do not steal redirects from "latest" content when it is moved around.
+Aliases must be relative to avoid redirecting latest content to old versions.
+
+If there is a page in the old documentation that has an alias that includes the version "latest", and the page referred to by that alias doesn't exist in the actual latest documentation, then Hugo creates a redirect at the page referred to by the alias.
+
+That redirect redirects the user from latest documentation into the old documentation.
 
 Aliases should include a YAML comment explaining the absolute URL path that the relative path redirects.
-This helps a reviewer check that your alias works correctly.
-For example, `../path/to/alias/ # /docs/grafana/<GRAFANA VERSION>/path/to/alias/`.
+This helps a reviewer confirm that your alias works correctly.
+
+A YAML comment starts with a hash (`#`).
+
+For example, the following Markdown front matter snippet, in the file `new-url.md`, defines an alias to redirect `/docs/grafana/<GRAFANA_VERSION/original-url/`.
+The comment `# /docs/grafana/<GRAFANA_VERSION>/original-url/` indicates the absolute URL path.
+
+```
+---
+aliases:
+  - ./original-url/ # /docs/grafana/<GRAFANA_VERSION>/original-url/
+---
+```
+
+##### Determine the relative alias
+
+To determine the relative alias, you must first understand the meaning of the current directory (`.`) and parent directory (`..`) path elements when they are used at the start of an alias.
 
-##### Examples
+For an alias in the page `/docs/grafana/latest/alerting/manage-notifications/`:
 
-To redirect the page `/docs/grafana/latest/alerting/silences/` to `/docs/grafana/latest/alerting/manage-notifications/create-silence/`, you must add a relative alias in the source file for `/docs/grafana/latest/alerting/manage-notifications/create-silence/` containing the relative alias to `/docs/grafana/latest/alerting/silences/`.
+- The current directory element (`.`) refers to the directory containing the current page.
 
-- The relative alias `./` refers to the page`/docs/grafana/latest/alerting/manage-notifications/` because that is the directory containing the page `/docs/grafana/latest/alerting/manage-notifications/create-silence/`.
-- The relative alias `../` refers to the page `/docs/grafana/latest/alerting/`.
-- The relative alias `../silences/` refers to the page `/docs/grafana/latest/alerting/silences/`.
+  In this example, this is the page `/docs/grafana/latest/alerting/manage-notifications/`.
 
-Therefore, with the alias `../silences/` in the source file for the page `/docs/grafana/latest/alerting/manage-notifications/create-silence/`, Hugo will create a redirect page at `/docs/grafana/latest/alerting/silences/`.
+- The parent directory element (`..`) refers to the parent directory of the current directory element.
 
-To redirect the page `/docs/grafana/latest/alerting/unified-alerting/` to `/docs/grafana/latest/alerting/` you must add a relative alias in the source file for `/docs/grafana/alerting/` containing the relative alias to `/docs/grafana/latest/alerting/unified-alerting/`.
+  In this example, this is the page `/docs/grafana/latest/alerting/`.
 
-- The relative alias `./` refers to the page `/docs/grafana/latest/` because that is the directory containing the page `/docs/grafana/latest/alerting/`.
-- The relative alias `./alerting/` refers to the page `/docs/grafana/latest/alerting/` which is the page itself.
-- The relative alias `./alerting/unified-alerting/` refers to the page `/docs/grafana/latest/alerting/unified-alerting/`.
+The following table demonstrates the redirect URL, **REDIRECT**, created when using the relative alias, **RELATIVE ALIAS**, in the source file for **DESTINATION**:
 
-Therefore, with the alias `./alerting/unified-alerting/` in the source file for the page `/docs/grafana/latest/alerting/`, Hugo will create a redirect page at `/docs/grafana/latest/alerting/unified-alerting/`.
+| DESTINATION                                           | RELATIVE ALIAS                           | REDIRECT                                                             |
+| ----------------------------------------------------- | ---------------------------------------- | -------------------------------------------------------------------- |
+| `/docs/grafana/latest/alerting/manage-notifications/` | `./`                                     | `/docs/grafana/latest/alerting/`                                     |
+| `/docs/grafana/latest/alerting/manage-notifications/` | `./silences/`                            | `/docs/grafana/latest/alerting/silences/`                            |
+| `/docs/grafana/latest/alerting/manage-notifications/` | `./manage-notifications/create-silence/` | `/docs/grafana/latest/alerting/manage-notifications/create-silence/` |
+| `/docs/grafana/latest/alerting/manage-notifications/` | `../`                                    | `/docs/grafana/latest/`                                              |
+| `/docs/grafana/latest/alerting/manage-notifications/` | `../old-alerting/`                       | `/docs/grafana/latest/old-alerting/`                                 |
 
 #### Other projects
 
-Include an `aliases` entry for the current URL path.
-Add an `aliases` entry to make it safer to move content around, as the redirect from old to new page location is already in place.
-Hugo doesn't create a redirect `.html` file when the directory is already populated with content.
-When a page is moved, update the `aliases` with the new URL path.
+- Include an `aliases` entry for the current URL path.
+- Add an `aliases` entry to make it safer to move content around, as the redirect from old to new page location is already in place.
+  Hugo doesn't create a redirect `.html` file when the directory is already populated with content.
+- When a page is moved, update the `aliases` with the new URL path.
 
 ### Test an alias