From c3b862c667146b89351455783645870581629a6e Mon Sep 17 00:00:00 2001 From: Jack Baldry Date: Thu, 2 Nov 2023 14:11:04 +0000 Subject: [PATCH] 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 * Update `doc-validator` to allow correct linking Signed-off-by: Jack Baldry * Fix linting Signed-off-by: Jack Baldry * Explicitly say that use of `relref` is discouraged and move reference content to Shortcodes page Co-authored-by: Isabel Matwawana Signed-off-by: Jack Baldry * Add examples to demonstrate how to link with version subsitution Signed-off-by: Jack Baldry * Exclusively use underscores for link version substitution Signed-off-by: Jack Baldry * Add example of absolute `relref` shortcode argument Closes https://github.com/grafana/writers-toolkit/issues/314. Signed-off-by: Jack Baldry * Update headings Co-authored-by: Isabel Matwawana Signed-off-by: Jack Baldry * Clarify that heading to anchor conversion is a task performed by the writer Co-authored-by: Isabel Matwawana Signed-off-by: Jack Baldry * Deduplicate instruction to set front matter for pages Co-authored-by: Isabel Matwawana Signed-off-by: Jack Baldry * Fix substitution explanation Co-authored-by: Isabel Matwawana Signed-off-by: Jack Baldry * Add warning about `relref` shortcode usage Signed-off-by: Jack Baldry * Demonstrate linking across pages and within the same page Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com> * State that it is the source page's front matter that is used for substitution Signed-off-by: Jack Baldry * Incorporate technical writer feedback Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com> Co-authored-by: Ursula Kallio --------- Signed-off-by: Jack Baldry Co-authored-by: Isabel Matwawana Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Ursula Kallio --- .github/workflows/validate-documentation.yml | 2 +- docs/sources/get-started/_index.md | 2 +- .../review/run-a-local-webserver/index.md | 2 +- docs/sources/write/links/index.md | 111 +++++++++++++ docs/sources/write/markdown-guide/index.md | 8 +- docs/sources/write/references/index.md | 147 ------------------ docs/sources/write/shortcodes/index.md | 127 ++++++++++++--- .../style-guide/write-for-developers/index.md | 2 - 8 files changed, 224 insertions(+), 177 deletions(-) create mode 100644 docs/sources/write/links/index.md delete mode 100644 docs/sources/write/references/index.md diff --git a/.github/workflows/validate-documentation.yml b/.github/workflows/validate-documentation.yml index 7de63795c..ee5e95a0c 100644 --- 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 index a3c5fe6ef..01e443749 100644 --- 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 index b20135bd4..0401bf1ad 100644 --- 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 new file mode 100644 index 000000000..dbccbdf35 --- /dev/null +++ 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//`, 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//developers/`. + +- If you're linking from Grafana documentation, `` is substituted with the version inferred from the page's URL. +- If you're linking from other documentation, `` 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//`, 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//release-notes/`. + +- If you're linking from Mimir documentation, `` is substituted with the version inferred from the page's URL. +- If you're linking from other documentation, `` 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//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 index bc36a01ba..a6f8101e4 100644 --- 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 deleted file mode 100644 index 0e02fd0eb..000000000 --- a/docs/sources/write/references/index.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -title: Links and cross references -menuTitle: Links and cross references -description: Understand how Hugo determines references, the different types of references, and how to use them. -weight: 600 -aliases: - - /docs/writers-toolkit/writing-guide/references/ - - /docs/writers-toolkit/write/references/ -keywords: - - Hugo - - references - - relref - - ref ---- - -# Links and cross references - -Links are a mechanism for reusing content. -Instead of writing the same information twice, you can link to a definitive source of truth. - -This page focuses only on HTTP-based URLs that have the scheme `http` or `https`. - -## Choose the correct link - -There are multiple ways to link to the same destination URL. -All of the following destinations link https://grafana.com/docs/grafana/latest/ to when followed from the page https://grafana.com/docs: - -- https://grafana.com/docs/grafana/latest/: a fully qualified URL. -- /docs/grafana/latest: a partial URL with an absolute path. -- ./grafana/latest: a partial URL with a relative path. - -**To choose the correct link:** - -1. If the source is reused as described in [Reuse directories of content with Hugo mounts]({{< relref "../reuse-content/reuse-directories" >}}), use the `docs/reference` shortcode. - - For more information about the `docs/reference` shortcode, refer to [`docs/reference` shortcode]({{< relref "../shortcodes#docsreference" >}}). - -1. If the destination is part of the current documentation set, use the `relref` shortcode. - - For example, `{{}}`. - - Hugo emits logs during the build for broken links defined with the `relref` shortcode. - For more information about the `relref` shortcode, refer to [Build time link checking with Hugo](#build-time-link-checking-with-hugo). - -1. Otherwise, use the fully qualified URL. - - For example, `[GitHub](https://github.com)`, or `[Grafana](https://grafana.com/docs/grafana/latest/)`. - -## Build time link checking with Hugo - -Hugo has built-in shortcodes for creating links. -The `ref` and `relref` shortcodes display the absolute and relative permalinks to a page, respectively. -They both provide build time link checking to ensure that the destination file exists. - -Relative references are the most common references in Grafana technical documentation. -This is the Hugo shortcode: `{{" */>}}`. - -{{% admonition type="note" %}} -Hugo link checking depends on having all the content available during the build. -In most projects, the only content available during local builds and CI is the current project documentation. -Therefore, the current advice is to only use the `relref` shortcode for links within the current project. -{{% /admonition %}} - -### Determine `relref` shortcode destinations - -The argument to the `relref` shortcode is the path to a source file in the Hugo content directory. -During local builds, the `docs/sources` directory is automatically mounted into the Hugo content directory. - -Hugo has different kinds of source files for producing pages. -These include: - -- page (`page.md`) -- leaf bundle (`page/index.md`) -- branch bundle (`page/_index.md`) - -Each of those source files produce the same page. -To avoid a link breaking when the source file changes kind, you can ignore the file extension and index kind. -You can reference each of the preceding examples with the same argument -- `page`. - -{{% admonition type="note" %}} -There is no trailing slash in the argument `page`. -Including a trailing slash prevents the argument working for some kinds of source files. -{{% /admonition %}} - -{{% admonition type="note" %}} -If the destination file or its containing directory has a period (`.`) in the path, you must link to the source file directly. -{{% /admonition %}} - -#### Example - -In the Writers' Toolkit repository, with the following directory structure: - -``` -docs -└── sources - ├── branch - │ └── _index.md - │ └── other.md - └── leaf - └── index.md -``` - -Hugo produces the following website pages: - -``` -/docs/writers-toolkit/branch/ -/docs/writers-toolkit/branch/other/ -/docs/writers-toolkit/leaf/ -``` - -Refer to the following table for the correct `relref` shortcode to use to link between each of the example pages. - -| Source page | Destination page | `relref` shortcode with relative path | `relref` shortcode with absolute path | -| ------------------------------------- | ------------------------------------- | -------------------------------------- | --------------------------------------------------------- | -| `/docs/writers-toolkit/branch/` | `/docs/writers-toolkit/branch/other/` | `{{}}` | `{{}}` | -| `/docs/writers-toolkit/branch/` | `/docs/writers-toolkit/leaf/` | `{{}}` | `{{}}` | -| `/docs/writers-toolkit/leaf/` | `/docs/writers-toolkit/branch/` | `{{}}` | `{{}}` | -| `/docs/writers-toolkit/leaf/` | `/docs/writers-toolkit/branch/other/` | `{{}}` | `{{}}` | -| `/docs/writers-toolkit/branch/other/` | `/docs/writers-toolkit/branch/` | `{{}}` | `{{}}` | -| `/docs/writers-toolkit/branch/other/` | `/docs/writers-toolkit/leaf/` | `{{}}` | `{{}}` | - -## Anchors - -In a reference, you can optionally include an anchor to a heading in the referenced page. -Specify and anchor at the end of the reference `#` followed by the normalized heading. - -Hugo normalizes headings to make anchors. -To convert a heading to an anchor, Hugo makes 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 (`-`). - -If the anchor is in the current page, you don't need to use `relref` syntax. -The following Markdown links are equivalent: - -- `[link text]({{}})` -- `[link text](#anchor-in-current-page)` - -### Hugo error output - - - -{{< docs/shared source="writers-toolkit" lookup="hugo-error-example-bad-link.md" version="" >}} - -For additional information about Hugo error output, refer to [Test documentation changes]({{< relref "../../review/run-a-local-webserver" >}}). diff --git a/docs/sources/write/shortcodes/index.md b/docs/sources/write/shortcodes/index.md index 4ee1f970f..dafd7f78e 100644 --- a/docs/sources/write/shortcodes/index.md +++ b/docs/sources/write/shortcodes/index.md @@ -289,12 +289,12 @@ To share content, follow these steps: 1. Store the file in a shared folder. 1. To include the shared content in a Markdown file, insert the `docs/shared` shortcode with the following named parameters: -| Parameter | Description | Required | -| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -| `lookup` | Path to the included content relative to the root of the shared directory. | yes | -| `source` | Name of the source content as shown on the website. For example, for https://grafana.com/docs/enterprise-metrics/ content, the _source_ is `enterprise-metrics`. | yes | -| `version` | Version of the source content to include. For source content that does not have a version, use the empty string `""` as the value. Version inference is supported using values like ``. To learn about version inference, refer to [About version inference](#about-version-inference). | yes | -| `leveloffset` | Manipulates source content headings up to a maximum level of `h6`. Only positive offsets are currently supported. `leveloffset="+5"` ensures an `h1` in the source content is an `h6` in the destination content. | no | +| Parameter | Description | Required | +| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| `lookup` | Path to the included content relative to the root of the shared directory. | yes | +| `source` | Name of the source content as shown on the website. For example, for https://grafana.com/docs/enterprise-metrics/ content, the _source_ is `enterprise-metrics`. | yes | +| `version` | Version of the source content to include. For source content that does not have a version, use the empty string `""` as the value. Version substitution is supported using values like ``. To learn about version substitution, refer to [About version substitution](#about-version-substitution). | yes | +| `leveloffset` | Manipulates source content headings up to a maximum level of `h6`. Only positive offsets are currently supported. `leveloffset="+5"` ensures an `h1` in the source content is an `h6` in the destination content. | no | {{% admonition type="note" %}} Hugo doesn't rebuild the destination file when a source file changes on disk. @@ -363,6 +363,77 @@ In this example, the image's display size is changed to have a maximum width of {{}} ``` + + +## Relref + + + +{{% admonition type="warning" %}} +This shortcode is present in the documentation, but is being deprecated in favor of fully qualified URLs. +Don't use it when creating new or updating existing documentation. +{{% /admonition %}} + +The `relref` shortcode provides build-time link checking to ensure that the destination file exists. + +For example: `{{}}`. + +| Parameter | Description | Required | +| ---------- | ---------------- | -------- | +| position 0 | The file lookup. | yes | + +The argument is an absolute or relative file lookup. +An absolute lookup begins with a slash (`/`) and starts from the site root. +For example, to link to the Grafana Cloud index page, the `relref` shortcode argument is `{{}}`. + +Using the full path to file, including the extension, can break the lookup if the destination file changes from a page to a leaf or branch bundle. +To avoid this, omit the file extension and any `/_index` or `/index` part of the lookup. +Using the previous example of the Grafana Cloud index page, the preferred `relref` shortcode argument is `{{}}`. + +Hugo link checking only applies to the content available during the build. +In most projects, the only content available during local builds and CI is the current project documentation, +so you should be aware that just because a link uses a `relref`, it doesn't automatically follow that the link can be checked. + +Emitted Hugo errors look like this: + + + +{{< docs/shared source="writers-toolkit" lookup="hugo-error-example-bad-link.md" version="" >}} + +For additional information about Hugo error output, refer to [Test documentation changes](https://grafana.com/docs/writers-toolkit/review/run-a-local-webserver/). + +### Determine `relref` shortcode arguments + +To determine the path between the source and destination content, do the following: + +Find the directory where the destination content lives. +Find the directory that the source and destination directories have in common. +Note the relative path from the common directory to the destination directory. +Count the number of folders from the source to the common directory and that number equals the number of parent directory path elements (`..`) you need to add to your relative path. +Join all the path elements together with forward slashes (`/`). + +For example, with the following folder structure: + +``` +Vehicles +├── Trucks +│ ├── F150 +│ └── 1999 F150 +└── Vans +``` + +In this case, the source content is in the `1999 F150` directory and the destination content is in the `Vans` directory. +The common folder for the two pieces of content is the `Vehicles` directory. + +The parent directory of `1999 F150` is `Trucks`, requiring one `..` path element. +To parent directory of `Trucks` is `Vehicles`, requiring another `..` path element. +Therefore, the relative path from the source directory, `1999 F150`, and the common directory, `Vehicles`, is `../..` + +The pathway from the common directory `Vehicles` to destination directory `Vans` is `vans` +The relative path is `../../vans` + +If the source directory was `Vans` and the destination was `1999 F150`, the relative path would be `../trucks/F150/1999-F150`. + ## Responsive-table The `responsive-table` shortcode wraps the table within the shortcode tags with a class that makes the table responsive to the browser window. @@ -437,9 +508,10 @@ For an example, refer to the definition of [graph](https://www.dictionary.com/br ## Docs/reference -The `docs/reference` shortcode offers more flexible linking than the Hugo built-in `relref` shortcode. +The `docs/reference` shortcode lets you specify different destinations for the same link that depend on where the source file is published. +Use this shortcode when content from one repository is published to more than one documentation set. -Use this shortcode when content from one repository is published to more than one documentation set, because it lets you specify appropriate links for each doc set in one part of the file (usually at end of the file, like a footer) while using the link label in the body text. +All possible destinations are set in one part of the file (usually at end of the file, like a footer). For example, a page in versioned Grafana documentation is also mounted in the Grafana Cloud documentation. The page in Grafana should link to the Grafana dashboards page but the page in Grafana Cloud should link to the Grafana Cloud dashboards page. @@ -455,18 +527,28 @@ Set the reference at the end of the page as follows: The content within the shortcode tags is as follows: -- `label` - The label you'll use in the reference-style links in the file. In the example above, the label is `dashboards`. The label can be multiple words (for example, [dashboard docs]) and can include spaces. -- `project path prefix` - Designates the target project. In the example above, the path prefixes are `/docs/grafana/` for Grafana and `/docs/grafana-cloud/` for Cloud. -- `reference` - The path to the destination file. Version inference is supported using values like ``. To learn about version inference, refer to [About version inference](#about-version-inference). +`[LABEL]: "PROJECT PATH PREFIX -> REFERENCE"` + +- _`LABEL`_ - The label you'll use in the reference-style links in the file. + In the example above, the label is `dashboards`. + The label can be multiple words (for example, [dashboard docs]) and can include spaces. + +- _`PROJECT PATH PREFIX`_ - Designates the target project. + In the example above, the path prefixes are `/docs/grafana/` for Grafana and `/docs/grafana-cloud/` for Cloud. + +- _`REFERENCE`_ - The path to the destination file. + Version substitution is supported using values like ``. + To learn about version substitution, refer to [About version substitution](#about-version-substitution). Then add the link in the body of the file in the following format: ```markdown -For more information about Grafana dashboards, refer to the [Dashboards documentation][dashboards]. +For more information about Grafana dashboards, refer to [Dashboards][dashboards]. ``` -- If the page you're on is `/docs/grafana/latest/alerting/`, the inferred version is `latest`, and the returned reference is `/docs/grafana/latest/dashboards`. -- If the page you're on is `/docs/grafana/next/alerting/`, the inferred version is `next`, and the returned reference is `/docs/grafana/next/dashboards`. +- If the page you're on is `/docs/grafana-cloud/alerting/`, the returned link is `/docs/grafana-cloud/dashboards/`. +- If the page you're on is `/docs/grafana/latest/alerting/`, the inferred version is `latest`, and the returned link is `/docs/grafana/latest/dashboards/`. +- If the page you're on is `/docs/grafana/next/alerting/`, the inferred version is `next`, and the returned link is `/docs/grafana/next/dashboards/`. ### Other use cases @@ -498,16 +580,17 @@ This Markdown renders as: {{}} ``` -## About version inference +## About version substitution -Version inference enables the use of absolute paths that resolve correctly, irrespective of version. -It uses special syntax using angle bracket delimiters like ``. +Version substitution enables the use of absolute paths that resolve correctly, irrespective of version. +It uses special syntax using angle bracket delimiters like ``. -As a convention, use the name of the target project, with spaces but no hyphens or underscores, all upper-case. -For example, `grafana` becomes `GRAFANA`, `grafana-cloud` becomes GRAFANA CLOUD. +As a convention, use the name of the target project all upper-case. +For example, `grafana` becomes `GRAFANA`, `grafana-cloud` becomes `GRAFANA CLOUD`. -The special syntax `` is substituted by the version that is inferred from the page's URL. +The special syntax `` is substituted by the version that is inferred from the page's URL. +If the page's URL has the prefix `/docs/grafana/latest/`, the syntax `` is replaced by `latest` in the final URL. You can override version inference by including additional metadata in the front matter of the file. -To override the value of ``, set the `GRAFANA VERSION` parameter in the page's front matter. -For example, to set the version to `next` irrespective of the source content version, add the following to the front matter: `GRAFANA VERSION: next`. +To override the value of ``, set the `GRAFANA_VERSION` parameter in the page's front matter. +For example, to set the version to `next` irrespective of the source content version, add the following to the front matter: `GRAFANA_VERSION: next`. diff --git a/docs/sources/write/style-guide/write-for-developers/index.md b/docs/sources/write/style-guide/write-for-developers/index.md index a0fa93d0c..92808b188 100644 --- a/docs/sources/write/style-guide/write-for-developers/index.md +++ b/docs/sources/write/style-guide/write-for-developers/index.md @@ -100,8 +100,6 @@ Introduce each code sample with a sentence or paragraph to establish its context Many types of information belong in fixed-width font. Among these are path names, file names, directories, or folders. However, don't format domain names or URLs as code if you intend the user to follow the link. -Although there are times when you might want to make a URL clickable, it is better to follow the guidelines for [References]({{< relref "../../references" >}}). - ## Command lines Use the following conventions when you include commands on the command line in technical content.