[release-v0.36] Replace docs/reference shortcode with ref URIs (#6885)

* Replace all docs/reference use with ref URIs Signed-off-by: Jack Baldry <[email protected]> * Use consistent underscore separated syntax Signed-off-by: Jack Baldry <[email protected]> * Fix missing parens Signed-off-by: Jack Baldry <[email protected]> (cherry picked from commit 7b41d2a) Signed-off-by: Jack Baldry <[email protected]> (cherry picked from commit 422d19a) Signed-off-by: Jack Baldry <[email protected]> --------- Signed-off-by: Jack Baldry <[email protected]>
grafana · May 21, 2024 · ca12b92 · ca12b92
1 parent 56ea457
commit ca12b92
Show file tree

Hide file tree

Showing 21 changed files with 382 additions and 244 deletions.
diff --git a/docs/sources/_index.md b/docs/sources/_index.md
@@ -9,6 +9,32 @@ description: Grafana Agent is a flexible, performant, vendor-neutral, telemetry
 weight: 350
 cascade:
   AGENT_RELEASE: v0.36.0
+refs:
+  variants:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/about/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/monitor-infrastructure/agent/about/
+  static-mode:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/static/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/monitor-infrastructure/agent/static/
+  flow-mode:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/flow/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/agent/<AGENT_VERSION>/flow/
+  static-mode-kubernetes-operator:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/operator/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/monitor-infrastructure/agent/operator/
+  ui:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/flow/monitoring/debugging/#grafana-agent-flow-ui
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/agent/<AGENT_VERSION>/flow/monitoring/debugging/#grafana-agent-flow-ui
 ---
 
 # Grafana Agent
@@ -54,17 +80,17 @@ Grafana Agent can collect, transform, and send data to:
 * **Battle-tested**: Grafana Agent extends the existing battle-tested code from
   the Prometheus and OpenTelemetry Collector projects.
 * **Powerful**: Write programmable pipelines with ease, and debug them using a
-  [built-in UI][UI].
+  [built-in UI](ref:ui).
 * **Batteries included**: Integrate with systems like MySQL, Kubernetes, and
   Apache to get telemetry that's immediately useful.
 
 ## Getting started
 
-* Choose a [variant][variants] of Grafana Agent to run.
+* Choose a [variant](ref:variants) of Grafana Agent to run.
 * Refer to the documentation for the variant to use:
-  * [Static mode][]
-  * [Static mode Kubernetes operator][]
-  * [Flow mode][]
+  * [Static mode](ref:static-mode)
+  * [Static mode Kubernetes operator](ref:static-mode-kubernetes-operator)
+  * [Flow mode](ref:flow-mode)
 
 ## Supported platforms
 
@@ -102,19 +128,3 @@ Patch and security releases may be created at any time.
 
 [Milestones]: https://github.com/grafana/agent/milestones
 
-{{% docs/reference %}}
-[variants]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/about"
-[variants]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/about"
-
-[Static mode]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/static"
-[Static mode]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/static"
-
-[Static mode Kubernetes operator]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/operator"
-[Static mode Kubernetes operator]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/operator"
-
-[Flow mode]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/flow"
-[Flow mode]: "/docs/grafana-cloud/ -> /docs/agent/<AGENT VERSION>/flow"
-
-[UI]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/flow/monitoring/debugging.md#grafana-agent-flow-ui"
-[UI]: "/docs/grafana-cloud/ -> /docs/agent/<AGENT VERSION>/flow/monitoring/debugging.md#grafana-agent-flow-ui"
-{{% /docs/reference %}}
diff --git a/docs/sources/about.md b/docs/sources/about.md
@@ -9,6 +9,32 @@ menuTitle: Introduction
 title: Introduction to Grafana Agent
 description: Grafana Agent is a flexible, performant, vendor-neutral, telemetry collector
 weight: 100
+refs:
+  flow-mode:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/flow/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/agent/<AGENT_VERSION>/flow/
+  components:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/flow/reference/components/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/agent/<AGENT_VERSION>/flow/reference/components/
+  static-mode-kubernetes-operator:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/operator/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/monitor-infrastructure/agent/operator/
+  static-mode:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/static/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/monitor-infrastructure/agent/static/
+  integrations:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/static/configuration/integrations/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/monitor-infrastructure/agent/static/configuration/integrations/
 ---
 
 # Introduction to Grafana Agent
@@ -19,20 +45,10 @@ such as Prometheus and OpenTelemetry.
 
 Grafana Agent is available in three different variants:
 
-- [Static mode][]: The default, original variant of Grafana Agent.
-- [Static mode Kubernetes operator][]: Variant which manages agents running in Static mode.
-- [Flow mode][]: The newer, more flexible re-imagining variant of Grafana Agent.
+- [Static mode](ref:static-mode): The default, original variant of Grafana Agent.
+- [Static mode Kubernetes operator](ref:static-mode-kubernetes-operator): Variant which manages agents running in Static mode.
+- [Flow mode](ref:flow-mode): The newer, more flexible re-imagining variant of Grafana Agent.
 
-{{% docs/reference %}}
-[Static mode]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/static"
-[Static mode]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/static"
-
-[Static mode Kubernetes operator]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/operator"
-[Static mode Kubernetes operator]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/operator"
-
-[Flow mode]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/flow"
-[Flow mode]: "/docs/grafana-cloud/ -> /docs/agent/<AGENT VERSION>/flow"
-{{% /docs/reference %}}
 
 ## Stability
 
@@ -49,7 +65,7 @@ Grafana Agent is available in three different variants:
 
 ### Static mode
 
-[Static mode][] is the original variant of Grafana Agent, first introduced on
+[Static mode](ref:static-mode) is the original variant of Grafana Agent, first introduced on
 March 3, 2020. Static mode is the most mature variant of Grafana Agent.
 
 You should run Static mode when:
@@ -58,12 +74,12 @@ You should run Static mode when:
 
 * **Grafana Cloud integrations**: You need to use Grafana Agent with Grafana Cloud integrations.
 
-* **Complete list of integrations**: You need to use a Static mode [integration][integrations] which is not yet
-  available as a [component][components] in Flow mode.
+* **Complete list of integrations**: You need to use a Static mode [integration](ref:integrations) which is not yet
+  available as a [component](ref:components) in Flow mode.
 
 ### Static mode Kubernetes operator
 
-The [Static mode Kubernetes operator][] is a variant of Grafana Agent first
+The [Static mode Kubernetes operator](ref:static-mode-kubernetes-operator) is a variant of Grafana Agent first
 introduced on June 17, 2021. It is currently in beta.
 
 The Static mode Kubernetes operator was introduced for compatibility with
@@ -78,7 +94,7 @@ You should run the Static mode Kubernetes operator when:
 
 ### Flow mode
 
-[Flow mode][] is a stable variant of Grafana Agent first introduced on
+[Flow mode](ref:flow-mode) is a stable variant of Grafana Agent first introduced on
 September 29, 2022.
 
 Flow mode was introduced as a re-imagining of Grafana Agent with a focus on
@@ -114,10 +130,3 @@ You should run Flow mode when:
 [BoringCrypto](https://pkg.go.dev/crypto/internal/boring) is an **EXPERIMENTAL** feature for building Grafana Agent
 binaries and images with BoringCrypto enabled. Builds and Docker images for Linux arm64/amd64 are made available.
 
-{{% docs/reference %}}
-[integrations]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/static/configuration/integrations"
-[integrations]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/static/configuration/integrations"
-
-[components]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/flow/reference/components"
-[components]: "/docs/grafana-cloud/ -> /docs/agent/<AGENT VERSION>/flow/reference/components"
-{{% /docs/reference %}}
diff --git a/docs/sources/data-collection.md b/docs/sources/data-collection.md
@@ -9,6 +9,25 @@ menuTitle: Data collection
 title: Grafana Agent data collection
 description: Grafana Agent data collection
 weight: 500
+refs:
+  flow:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/flow/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/agent/<AGENT_VERSION>/flow/
+  static:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/static/
+  command-line-flag:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/flow/reference/cli/run/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/agent/<AGENT_VERSION>/flow/reference/cli/run/
+  components:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/flow/concepts/components/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/agent/<AGENT_VERSION>/flow/reference/cli/run/
 ---
 
 # Data collection
@@ -26,23 +45,13 @@ The usage information includes the following details:
 * Version of running Grafana Agent.
 * Operating system Grafana Agent is running on.
 * System architecture Grafana Agent is running on.
-* List of enabled feature flags ([Static] mode only).
-* List of enabled integrations ([Static] mode only).
-* List of enabled [components][] ([Flow] mode only).
+* List of enabled feature flags ([Static](ref:static) mode only).
+* List of enabled integrations ([Static](ref:static) mode only).
+* List of enabled [components](ref:components) ([Flow](ref:flow) mode only).
 
 This list may change over time. All newly reported data is documented in the CHANGELOG.
 
 ## Opt-out of data collection
 
-You can use the `-disable-reporting` [command line flag][] to disable the reporting and opt-out of the data collection.
-
-{{% docs/reference %}}
-[command line flag]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/cli/run.md"
-[command line flag]: "/docs/grafana-cloud/ -> /docs/agent/<AGENT_VERSION>/flow/reference/cli/run.md"
-[components]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/concepts/components.md"
-[components]: "/docs/grafana-cloud/ -> /docs/agent/<AGENT_VERSION>/flow/reference/cli/run.md"
-[Static]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/static"
-[Static]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/static
-[Flow]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow"
-[Flow]: "/docs/grafana-cloud/ -> /docs/agent/<AGENT_VERSION>/flow"
-{{% /docs/reference %}}
+You can use the `-disable-reporting` [command line flag](ref:command-line-flag) to disable the reporting and opt-out of the data collection.
+
diff --git a/docs/sources/flow/setup/install/_index.md b/docs/sources/flow/setup/install/_index.md
@@ -9,6 +9,12 @@ menuTitle: Install flow mode
 title: Install Grafana Agent in flow mode
 description: Learn how to install Grafana Agent in flow mode
 weight: 50
+refs:
+  data-collection:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/data-collection/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/monitor-infrastructure/agent/data-collection/
 ---
 
 # Install Grafana Agent in flow mode
@@ -30,10 +36,6 @@ Installing Grafana Agent on other operating systems is possible, but is not reco
 
 ## Data collection
 
-By default, Grafana Agent sends anonymous usage information to Grafana Labs. Refer to [data collection][] for more information
+By default, Grafana Agent sends anonymous usage information to Grafana Labs. Refer to [data collection](ref:data-collection) for more information
 about what data is collected and how you can opt-out.
 
-{{% docs/reference %}}
-[data collection]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/data-collection.md"
-[data collection]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/data-collection.md"
-{{% /docs/reference %}}
diff --git a/docs/sources/operator/release-notes.md b/docs/sources/operator/release-notes.md
@@ -11,6 +11,17 @@ title: Release notes for Grafana Agent Operator
 description: Release notes for Grafana Agent Operator
 
 weight: 999
+refs:
+  release-notes-static:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/static/release-notes/
+    - pattern: /docs/agent/
+      destination: /docs/grafana-cloud/monitor-infrastructure/agent/static/release-notes/
+  release-notes-flow:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/flow/release-notes/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/agent/<AGENT_VERSION>/flow/release-notes/
 ---
 
 # Release notes for Grafana Agent Operator
@@ -22,16 +33,9 @@ For a complete list of changes to Grafana Agent, with links to pull requests and
 > **Note:** These release notes are specific to the Static mode Kubernetes Operator.
 > Other release notes for the different Grafana Agent variants are contained on separate pages:
 >
-> - [Static mode release notes][release-notes-static]
-> - [Flow mode release notes][release-notes-flow]
+> - [Static mode release notes](ref:release-notes-static)
+> - [Flow mode release notes](ref:release-notes-flow)
 
-{{% docs/reference %}}
-[release-notes-static]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/static/release-notes"
-[release-notes-static]: "/docs/agent/ -> /docs/grafana-cloud/monitor-infrastructure/agent/static/release-notes"
-
-[release-notes-flow]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/flow/release-notes"
-[release-notes-flow]: "/docs/grafana-cloud/ -> /docs/agent/<AGENT VERSION>/flow/release-notes"
-{{% /docs/reference %}}
 
 ## v0.33
 

diff --git a/docs/sources/static/_index.md b/docs/sources/static/_index.md
@@ -3,6 +3,22 @@ canonical: https://grafana.com/docs/agent/latest/static/
 title: Static mode
 description: Learn about Grafana Agent in static mode
 weight: 200
+refs:
+  install:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/static/set-up/install/
+    - pattern: /docs/grafana-cloud/
+      destination: ./set-up/install/
+  set-up:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/static/set-up/
+    - pattern: /docs/grafana-cloud/
+      destination: ./set-up/
+  configure:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/static/configuration/
+    - pattern: /docs/grafana-cloud/
+      destination: ./configuration/
 ---
 
 # Static mode
@@ -20,7 +36,7 @@ Static mode is composed of different _subsystems_:
   traces and forwarding them to Grafana Tempo or any OpenTelemetry-compatible
   endpoint.
 
-Static mode is [configured][configure] with a YAML file.
+Static mode is [configured](ref:configure) with a YAML file.
 
 Static mode works with:
 
@@ -31,7 +47,7 @@ Static mode works with:
 This topic helps you to think about what you're trying to accomplish and how to
 use Grafana Agent to meet your goals.
 
-You can [set up][] and [configure][] Grafana Agent in static mode manually, or
+You can [set up](ref:set-up) and [configure](ref:configure) Grafana Agent in static mode manually, or
 you can follow the common workflows described in this topic.
 
 ## Topics
@@ -64,7 +80,7 @@ Grafana Cloud integration workflows and the Kubernetes Monitoring solution are t
 
 | Topic | Description |
 |---|---|
-| [Install or uninstall Grafana Agent][install] | Install or uninstall Grafana Agent. |
+| [Install or uninstall Grafana Agent](ref:install) | Install or uninstall Grafana Agent. |
 | [Troubleshoot Cloud Integrations installation on Linux](/docs/grafana-cloud/monitor-infrastructure/integrations/install-troubleshoot-linux/) | Troubleshoot common errors when executing the Grafana Agent installation script on Linux.  |
 | [Troubleshoot Cloud Integrations installation on Mac](/docs/grafana-cloud/monitor-infrastructure/integrations/install-troubleshoot-mac/) | Troubleshoot common errors when executing the Grafana Agent installation script on Mac.  |
 | [Troubleshoot Cloud Integrations installation on Windows](/docs/grafana-cloud/monitor-infrastructure/integrations/install-troubleshooting-windows/) | Troubleshoot common errors when executing the Grafana Agent installation script on Windows.  |
@@ -84,11 +100,3 @@ Logs are included when you [set up a Cloud integration](/docs/grafana-cloud/data
 | [Set up and use tracing](/docs/grafana-cloud/data-configuration/traces/set-up-and-use-tempo/) |  Install Grafana Agent to collect traces for use with Grafana Tempo, included with your [Grafana Cloud account](/docs/grafana-cloud/account-management/cloud-portal/). |
 | [Use Grafana Agent as a tracing pipeline](/docs/tempo/latest/configuration/grafana-agent/) | Grafana Agent can be configured to run a set of tracing pipelines to collect data from your applications and write it to Grafana Tempo. Pipelines are built using OpenTelemetry, and consist of receivers, processors, and exporters. |
 
-{{% docs/reference %}}
-[set up]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/static/set-up"
-[set up]: "/docs/grafana-cloud/ -> ./set-up"
-[configure]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/static/configuration"
-[configure]: "/docs/grafana-cloud/ -> ./configuration"
-[install]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/static/set-up/install"
-[install]: "/docs/grafana-cloud/ -> ./set-up/install"
-{{% /docs/reference %}}