From 50bb5e056a33de6cac293bd8304246c94bd43501 Mon Sep 17 00:00:00 2001 From: Jack Baldry Date: Wed, 6 Sep 2023 13:01:35 +0100 Subject: [PATCH] Update `docs/shared` documentation to reflect new version inference interface (#309) * Update `docs/shared` documentation to reflect new version inference interface Signed-off-by: Jack Baldry * Avoid "unversioned" * Document intent rather than behavior Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com> * Clarify substitution behavior --------- Signed-off-by: Jack Baldry Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com> --- docs/sources/write/shortcodes/index.md | 39 +++++++++++++++----------- 1 file changed, 23 insertions(+), 16 deletions(-) diff --git a/docs/sources/write/shortcodes/index.md b/docs/sources/write/shortcodes/index.md index 9c18f1ac8..7f6f2cd91 100644 --- a/docs/sources/write/shortcodes/index.md +++ b/docs/sources/write/shortcodes/index.md @@ -124,12 +124,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. If not provided, _version_ is implicitly set to match the version of the destination content. If the including destination is at version `1.0.0`, then the version of included content is `1.0.0` also. | no | -| `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 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 | {{% admonition type="note" %}} Hugo doesn't rebuild the destination file when a source file changes on disk. @@ -141,14 +141,14 @@ To trigger a rebuild after changes to a source file, perform a trivial change to The following shortcode inserts the content from the `oauth2-block.md` file. The _lookup_ path is relative to the `shared` folder in the `agent` source repository. ```markdown -{{}} +{{" */>}} ``` The following shortcode inserts the latest version of `shared-page.md` from the `shared` folder in the `enterprise-metrics` project. Headings are offset by one level, so if the source content contains an `h1`, the resulting heading is an `h2`. ```markdown -{{}} +{{" leveloffset="+1" */>}} ``` ## `figure` shortcode @@ -248,10 +248,7 @@ 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. It can include ``, which is either taken from front matter of the page or falls back to being inferred from the version of the page. - This enables the use of absolute paths that resolve correctly, irrespective of version. - When including a version, for the target project, use the name of the project, with spaces but no hyphens or underscores, all upper-case. - For example, `grafana` becomes `GRAFANA`, `grafana-cloud` becomes GRAFANA 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). Then add the link in the body of the file in the following format: @@ -262,10 +259,6 @@ For more information about Grafana dashboards, refer to the [Dashboards document - 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`. -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, with the front matter `grafana_version: next`, the shortcode replaces `` with `next`. - ### Other use cases The `docs/reference` shortcode is also useful when you want to link to the same destination multiple times in one file. @@ -296,3 +289,17 @@ This Markdown renders as: ```markdown {{}} ``` + +## About version inference + +Version inference 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. + +The special syntax `` is substituted by the version that is inferred from the page's 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`.