Update link guidance to reflect current advice (#345)

* Restructured links and references page * Rewrote linking desitnation section * Fixed linting errors Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Update linking advice - Discourage `relref` shortcode. - Prefer fully qualified URLs with version substition for https://grafana.com pages. Signed-off-by: Jack Baldry <[email protected]> * Update `doc-validator` to allow correct linking Signed-off-by: Jack Baldry <[email protected]> * Fix linting Signed-off-by: Jack Baldry <[email protected]> * Explicitly say that use of `relref` is discouraged and move reference content to Shortcodes page Co-authored-by: Isabel Matwawana <[email protected]> Signed-off-by: Jack Baldry <[email protected]> * Add examples to demonstrate how to link with version subsitution Signed-off-by: Jack Baldry <[email protected]> * Exclusively use underscores for link version substitution Signed-off-by: Jack Baldry <[email protected]> * Add example of absolute `relref` shortcode argument Closes #314. Signed-off-by: Jack Baldry <[email protected]> * Update headings Co-authored-by: Isabel Matwawana <[email protected]> Signed-off-by: Jack Baldry <[email protected]> * Clarify that heading to anchor conversion is a task performed by the writer Co-authored-by: Isabel Matwawana <[email protected]> Signed-off-by: Jack Baldry <[email protected]> * Deduplicate instruction to set front matter for pages Co-authored-by: Isabel Matwawana <[email protected]> Signed-off-by: Jack Baldry <[email protected]> * Fix substitution explanation Co-authored-by: Isabel Matwawana <[email protected]> Signed-off-by: Jack Baldry <[email protected]> * Add warning about `relref` shortcode usage Signed-off-by: Jack Baldry <[email protected]> * Demonstrate linking across pages and within the same page Co-authored-by: Isabel <[email protected]> * State that it is the source page's front matter that is used for substitution Signed-off-by: Jack Baldry <[email protected]> * Incorporate technical writer feedback Co-authored-by: Isabel <[email protected]> Co-authored-by: Ursula Kallio <[email protected]> --------- Signed-off-by: Jack Baldry <[email protected]> Co-authored-by: Isabel Matwawana <[email protected]> Co-authored-by: Isabel <[email protected]> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Ursula Kallio <[email protected]>
grafana · Nov 2, 2023 · c3b862c · c3b862c
1 parent a7d9dd3
commit c3b862c
Show file tree

Hide file tree

Showing 8 changed files with 224 additions and 177 deletions.
diff --git a/.github/workflows/validate-documentation.yml b/.github/workflows/validate-documentation.yml
@@ -7,7 +7,7 @@ jobs:
   doc-validator:
     runs-on: "ubuntu-latest"
     container:
-      image: "grafana/doc-validator:v3.2.0"
+      image: "grafana/doc-validator:v4.0.0"
     steps:
       - name: "Checkout code"
         uses: "actions/checkout@v3"

diff --git a/docs/sources/get-started/_index.md b/docs/sources/get-started/_index.md
@@ -55,7 +55,7 @@ If you have questions, you can ask them in the [Grafana Community Slack #docs ch
 
 1. Add images and media. Read the [Images and media]({{< relref "../write/image-guidelines" >}}) documentation.
 
-1. Use links and references. Refer to the [Links and references]({{< relref "../write/references" >}}) documentation for guidance.
+1. Use links. Refer to the [Links](https://grafana.com/docs/writers-toolkit/write/links/) documentation for guidance.
 
 1. Add code samples. Refer to the [Code samples]({{< relref "../write/markdown-guide#code-blocks" >}}) documentation for guidance.
 

diff --git a/docs/sources/review/run-a-local-webserver/index.md b/docs/sources/review/run-a-local-webserver/index.md
@@ -79,7 +79,7 @@ When you save a file with an active local build, the page is rechecked. If the e
 
 {{< docs/shared source="writers-toolkit" lookup="hugo-error-example-bad-link.md" version="" >}}
 
-For more information about linking, refer to [Links and cross references]({{< relref "../../write/references" >}}).
+For more information about linking, refer to [Links](https://grafana.com/docs/writers-toolkit/write/links/).
 
 ### Example: Rebuild failed due to missing shortcode
 

diff --git a/docs/sources/write/links/index.md b/docs/sources/write/links/index.md
@@ -0,0 +1,111 @@
+---
+title: Links
+description: Understand how to link between pages.
+weight: 600
+aliases:
+  - /docs/writers-toolkit/write/links/
+  - /docs/writers-toolkit/write/references/
+  - /docs/writers-toolkit/writing-guide/references/
+keywords:
+  - Hugo
+  - link
+  - linking
+  - links
+  - ref
+  - references
+  - relref
+---
+
+# Links
+
+Choose your link type based on the applicable scenario:
+
+- [Link from source content that's used in multiple projects](#link-from-source-content-thats-used-in-multiple-projects)
+- [Link to grafana.com pages](#link-to-grafanacom-pages)
+- [Link to external pages](#link-to-external-pages)
+- [Link to page headings](#link-to-page-headings)
+
+Although these other types of links still function, replace them with full URLs:
+
+- [Hugo `relref` shortcode](https://grafana.com/docs/writers-toolkit/write/shortcodes/#relref)
+
+## Link from source content that's used in multiple projects
+
+Use the `docs/reference` shortcode.
+
+The source is reused as described in [Reuse directories of content with Hugo mounts](https://grafana.com/docs/writers-toolkit/write/reuse-content/reuse-directories/).
+For more information and examples, refer to [`docs/reference` shortcode](https://grafana.com/docs/writers-toolkit/write/shortcodes/#docsreference).
+
+## Link to grafana.com pages
+
+Use a full URL with version substitution syntax (if needed).
+
+Version substitution is necessary for full URLs to link to the correct version of documentation.
+Usually, this is the current version of documentation.
+
+In versioned documentation, set the correct version in the root `_index.md` file for your documentation.
+The following YAML example merges with the existing front matter in the root `_index.md` file, and sets `GRAFANA_VERSION` to be `latest` for that page and all child pages.
+
+```yaml
+cascade:
+  GRAFANA_VERSION: latest
+```
+
+### Examples
+
+**Link to Grafana documentation**:
+
+Start with `https://grafana.com/docs/grafana/<GRAFANA_VERSION>/`, and add the rest of the URL path.
+
+For example, to link to the [Developers](https://grafana.com/docs/grafana/latest/developers) page with version substitution,
+use `https://grafana.com/docs/grafana/<GRAFANA_VERSION>/developers/`.
+
+- If you're linking from Grafana documentation, `<GRAFANA_VERSION>` is substituted with the version inferred from the page's URL.
+- If you're linking from other documentation, `<GRAFANA_VERSION>` is substituted with the value of `GRAFANA_VERSION` from the source page's front matter.
+
+**Link to Grafana Cloud documentation**:
+
+Grafana Cloud documentation is not versioned so no version substitution syntax is needed.
+Use the full URL.
+For example, to link to the [Author and run tests](https://grafana.com/docs/grafana-cloud/k6/author-run/) page, use `https://grafana.com/docs/grafana-cloud/k6/author-run/`.
+
+**Link to Mimir documentation**:
+
+Start with `https://grafana.com/docs/grafana/<MIMIR_VERSION>/`, and add the rest of the URL path.
+
+For example, to link to the [Release notes](https://grafana.com/docs/mimir/latest/release-notes/) page with version substitution,
+use `https://grafana.com/docs/mimir/<MIMIR_VERSION>/release-notes/`.
+
+- If you're linking from Mimir documentation, `<MIMIR_VERSION>` is substituted with the version inferred from the page's URL.
+- If you're linking from other documentation, `<MIMIR_VERSION>` is substituted with the value of `MIMIR_VERSION` from the source page's front matter.
+
+## Link to external pages
+
+Use the full URL.
+For example, `https://github.com`.
+
+## Link to page headings
+
+Link to a heading on a page in one of two ways.
+
+From within the same page:
+
+```markdown
+Read more in the [Configuration section](#configuration) of this page.
+```
+
+From a different page:
+
+```markdown
+Read more in the [Grafana Open Source section of the Introduction page](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/fundamentals/#grafana-open-source).
+```
+
+To convert a heading to an anchor, make the following changes:
+
+1. Convert to lower case.
+1. Remove any period characters (`.`).
+1. Replace any character that's not a lower cased letter, a number, or an underscore (`_`) with dashes (`-`).
+1. Trim any preceding or proceeding dashes (`-`).
+1. Prefix with a `#`.
+
+The heading _Link to page headings_ becomes the anchor `#link-to-page-headings`.
diff --git a/docs/sources/write/markdown-guide/index.md b/docs/sources/write/markdown-guide/index.md
@@ -64,11 +64,13 @@ For the title of the page, use one `#`. For each child heading, use two `##` sym
 
 Displays as:
 
-**Note:** The distributor only passes _valid_ data to the ingesters.
+{{% admonition type="note" %}}
+The distributor only passes _valid_ data to the ingesters.
+{{% /admonition %}}
 
-## Links and references
+## Links
 
-For information about creating links between topics inside and outside of a Grafana Labs repository, refer to [Links and cross references]({{< relref "../references" >}}).
+For information about creating links between topics inside and outside of a Grafana Labs repository, refer to [Links](https://grafana.com/docs/writers-toolkit/write/links/).
 
 There are two forms of links in Markdown: inline and reference-style.
 

diff --git a/docs/sources/write/references/index.md b/docs/sources/write/references/index.md