Replace docs/reference shortcode with ref URIs (#6883)

* Replace all docs/reference use with ref URIs Signed-off-by: Jack Baldry <[email protected]> * Regenerate generated files Signed-off-by: Jack Baldry <[email protected]> * Fix missing parens Signed-off-by: Jack Baldry <[email protected]> --------- Signed-off-by: Jack Baldry <[email protected]>
grafana · May 21, 2024 · ecfb3ed · ecfb3ed
1 parent 7ebd285
commit ecfb3ed
Show file tree

Hide file tree

Showing 73 changed files with 1,637 additions and 982 deletions.
diff --git a/docs/sources/_index.md b/docs/sources/_index.md
@@ -11,6 +11,32 @@ weight: 350
 cascade:
   AGENT_RELEASE: v0.40.5
   OTEL_VERSION: v0.96.0
+refs:
+  variants:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/about/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/send-data/agent/about/
+  static-mode:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/static/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/send-data/agent/static/
+  static-mode-kubernetes-operator:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/operator/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/send-data/agent/operator/
+  flow-mode:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/flow/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/agent/<AGENT_VERSION>/flow/
+  ui:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/flow/tasks/debug/#grafana-agent-flow-ui
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/agent/<AGENT_VERSION>/flow/tasks/debug/#grafana-agent-flow-ui
 ---
 
 # Grafana Agent
@@ -55,17 +81,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
 
@@ -106,19 +132,3 @@ updates.
 
 Patch and security releases may be created at any time.
 
-{{% docs/reference %}}
-[variants]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/about"
-[variants]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/about"
-
-[Static mode]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/static"
-[Static mode]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/static"
-
-[Static mode Kubernetes operator]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/operator"
-[Static mode Kubernetes operator]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/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/tasks/debug.md#grafana-agent-flow-ui"
-[UI]: "/docs/grafana-cloud/ -> /docs/agent/<AGENT_VERSION>/flow/tasks/debug.md#grafana-agent-flow-ui"
-{{% /docs/reference %}}
diff --git a/docs/sources/_index.md.t b/docs/sources/_index.md.t
@@ -11,6 +11,32 @@ weight: 350
 cascade:
   AGENT_RELEASE: $AGENT_VERSION
   OTEL_VERSION: v0.96.0
+refs:
+  variants:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/about/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/send-data/agent/about/
+  static-mode:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/static/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/send-data/agent/static/
+  static-mode-kubernetes-operator:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/operator/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/send-data/agent/operator/
+  flow-mode:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/flow/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/agent/<AGENT_VERSION>/flow/
+  ui:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/flow/tasks/debug/#grafana-agent-flow-ui
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/agent/<AGENT_VERSION>/flow/tasks/debug/#grafana-agent-flow-ui
 ---
 
 # Grafana Agent
@@ -55,17 +81,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
 
@@ -106,19 +132,3 @@ updates.
 
 Patch and security releases may be created at any time.
 
-{{% docs/reference %}}
-[variants]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/about"
-[variants]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/about"
-
-[Static mode]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/static"
-[Static mode]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/static"
-
-[Static mode Kubernetes operator]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/operator"
-[Static mode Kubernetes operator]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/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/tasks/debug.md#grafana-agent-flow-ui"
-[UI]: "/docs/grafana-cloud/ -> /docs/agent/<AGENT_VERSION>/flow/tasks/debug.md#grafana-agent-flow-ui"
-{{% /docs/reference %}}
diff --git a/docs/sources/about.md b/docs/sources/about.md
@@ -10,6 +10,62 @@ description: Grafana Agent is a flexible, performant, vendor-neutral, telemetry
 menuTitle: Introduction
 title: Introduction to Grafana Agent
 weight: 100
+refs:
+  otel:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/flow/tasks/collect-opentelemetry-data/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/agent/<AGENT_VERSION>/flow/tasks/collect-opentelemetry-data/
+  vault:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/flow/reference/components/remote.vault/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/agent/<AGENT_VERSION>/flow/reference/components/remote.vault/
+  rules:
+    - pattern: /docs/agent/
+      destination: /docs/agent/latest/flow/reference/components/mimir.rules.kubernetes/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/agent/latest/flow/reference/components/mimir.rules.kubernetes/
+  loki:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/flow/tasks/migrate/from-promtail/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/agent/<AGENT_VERSION>/flow/tasks/migrate/from-promtail/
+  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/send-data/agent/operator/
+  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:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/static/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/send-data/agent/static/
+  prometheus:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/flow/tasks/collect-prometheus-metrics/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/agent/<AGENT_VERSION>/flow/tasks/collect-prometheus-metrics/
+  clustering:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/flow/concepts/clustering//
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/agent/<AGENT_VERSION>/flow/concepts/clustering//
+  integrations:
+    - pattern: /docs/agent/
+      destination: /docs/agent/<AGENT_VERSION>/static/configuration/integrations/
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana-cloud/send-data/agent/static/configuration/integrations/
 ---
 
 # Introduction to Grafana Agent
@@ -18,30 +74,10 @@ Grafana Agent is a flexible, high performance, vendor-neutral telemetry collecto
 
 Grafana Agent is available in three different variants:
 
-- [Static mode][]: The original Grafana Agent.
-- [Static mode Kubernetes operator][]: The Kubernetes operator for Static mode.
-- [Flow mode][]: The new, component-based Grafana Agent.
-
-{{% docs/reference %}}
-[Static mode]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/static"
-[Static mode]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/static"
-[Static mode Kubernetes operator]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/operator"
-[Static mode Kubernetes operator]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/operator"
-[Flow mode]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow"
-[Flow mode]: "/docs/grafana-cloud/ -> /docs/agent/<AGENT_VERSION>/flow"
-[Prometheus]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/tasks/collect-prometheus-metrics.md"
-[Prometheus]: "/docs/grafana-cloud/ -> /docs/agent/<AGENT_VERSION>/flow/tasks/collect-prometheus-metrics.md"
-[OTel]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/tasks/collect-opentelemetry-data.md"
-[OTel]: "/docs/grafana-cloud/ -> /docs/agent/<AGENT_VERSION>/flow/tasks/collect-opentelemetry-data.md"
-[Loki]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/tasks/migrate/from-promtail.md"
-[Loki]: "/docs/grafana-cloud/ -> /docs/agent/<AGENT_VERSION>/flow/tasks/migrate/from-promtail.md"
-[clustering]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/concepts/clustering/_index.md"
-[clustering]: "/docs/grafana-cloud/ -> /docs/agent/<AGENT_VERSION>/flow/concepts/clustering/_index.md"
-[rules]: "/docs/agent/ -> /docs/agent/latest/flow/reference/components/mimir.rules.kubernetes.md"
-[rules]: "/docs/grafana-cloud/ -> /docs/agent/latest/flow/reference/components/mimir.rules.kubernetes.md"
-[vault]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/components/remote.vault.md"
-[vault]: "/docs/grafana-cloud/ -> /docs/agent/<AGENT_VERSION>/flow/reference/components/remote.vault.md"
-{{% /docs/reference %}}
+- [Static mode](ref:static-mode): The original Grafana Agent.
+- [Static mode Kubernetes operator](ref:static-mode-kubernetes-operator): The Kubernetes operator for Static mode.
+- [Flow mode](ref:flow-mode): The new, component-based Grafana Agent.
+
 
 [Pyroscope]: https://grafana.com/docs/pyroscope/latest/configure-client/grafana-agent/go_pull
 [helm chart]: https://grafana.com/docs/grafana-cloud/monitor-infrastructure/kubernetes-monitoring/configuration/config-k8s-helmchart
@@ -69,19 +105,19 @@ Each variant of Grafana Agent provides a different level of functionality. The f
 
 |              | Grafana Agent Flow mode  | Grafana Agent Static mode | Grafana Agent Operator | OpenTelemetry Collector | Prometheus Agent mode |
 |--------------|--------------------------|---------------------------|------------------------|-------------------------|-----------------------|
-| **Metrics**  | [Prometheus][], [OTel][] | Prometheus                | Prometheus             | OTel                    | Prometheus            |
-| **Logs**     | [Loki][], [OTel][]       | Loki                      | Loki                   | OTel                    | No                    |
-| **Traces**   | [OTel][]                 | OTel                      | OTel                   | OTel                    | No                    |
+| **Metrics**  | [Prometheus](ref:prometheus), [OTel](ref:otel) | Prometheus                | Prometheus             | OTel                    | Prometheus            |
+| **Logs**     | [Loki](ref:loki), [OTel](ref:otel)       | Loki                      | Loki                   | OTel                    | No                    |
+| **Traces**   | [OTel](ref:otel)                 | OTel                      | OTel                   | OTel                    | No                    |
 | **Profiles** | [Pyroscope][]            | No                        | No                     | Planned                 | No                    |
 
 #### **OSS features**
 
 |                          | Grafana Agent Flow mode | Grafana Agent Static mode | Grafana Agent Operator | OpenTelemetry Collector | Prometheus Agent mode |
 |--------------------------|-------------------------|---------------------------|------------------------|-------------------------|-----------------------|
 | **Kubernetes native**    | [Yes][helm chart]       | No                        | Yes                    | Yes                     | No                    |
-| **Clustering**           | [Yes][clustering]       | No                        | No                     | No                      | No                    |
-| **Prometheus rules**     | [Yes][rules]            | No                        | No                     | No                      | No                    |
-| **Native Vault support** | [Yes][vault]            | No                        | No                     | No                      | No                    |
+| **Clustering**           | [Yes](ref:clustering)       | No                        | No                     | No                      | No                    |
+| **Prometheus rules**     | [Yes](ref:rules)            | No                        | No                     | No                      | No                    |
+| **Native Vault support** | [Yes](ref:vault)            | No                        | No                     | No                      | No                    |
 
 #### Grafana Cloud solutions
 
@@ -94,7 +130,7 @@ Each variant of Grafana Agent provides a different level of functionality. The f
 
 ### Static mode
 
-[Static mode][] is the original variant of Grafana Agent, introduced on March 3, 2020.
+[Static mode](ref:static-mode) is the original variant of Grafana Agent, introduced on March 3, 2020.
 Static mode is the most mature variant of Grafana Agent.
 
 You should run Static mode when:
@@ -110,7 +146,7 @@ Grafana Agent version 0.37 and newer provides Prometheus Operator compatibility
 You should use Grafana Agent Flow mode for all new Grafana Agent deployments.
 {{< /admonition >}}
 
-The [Static mode Kubernetes operator][] is a variant of Grafana Agent introduced on June 17, 2021. It's currently in beta.
+The [Static mode Kubernetes operator](ref:static-mode-kubernetes-operator) is a variant of Grafana Agent introduced on June 17, 2021. It's currently in beta.
 
 The Static mode Kubernetes operator provides compatibility with Prometheus Operator,
 allowing static mode to support resources from Prometheus Operator, such as ServiceMonitors, PodMonitors, and Probes.
@@ -123,7 +159,7 @@ You should run the Static mode Kubernetes operator when:
 
 ### Flow mode
 
-[Flow mode][] is a stable variant of Grafana Agent, introduced on September 29, 2022.
+[Flow mode](ref:flow-mode) is a stable variant of Grafana Agent, introduced on September 29, 2022.
 
 Grafana Agent Flow mode focuses on vendor neutrality, ease-of-use,
 improved debugging, and ability to adapt to the needs of power users by adopting a configuration-as-code model.
@@ -147,10 +183,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/send-data/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
@@ -10,6 +10,25 @@ description: Grafana Agent data collection
 menuTitle: Data collection
 title: Grafana Agent data collection
 weight: 500
+refs:
+  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/
+  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/
 ---
 
 # Grafana Agent Data collection
@@ -27,24 +46,14 @@ 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).
 * Method used to deploy Grafana Agent, for example Docker, Helm, RPM, or Operator.
 
 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/send-data/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.
+