Update cross reference syntax in Agent static mode documentation (#4814)

* First pass at updating references * Remove note admonition * Adjust ref syntax * Trying different syntax * Restory syntax to documented style * Ensure that Hugo knows the documentation is versioned Allows interpoloation of the `<GRAFANA VERSION>` variable used in the `docs/reference` shortcode. Signed-off-by: Jack Baldry <[email protected]> * Use more appropriate version variable Signed-off-by: Jack Baldry <[email protected]> * Update cross references in setup * Update install cross references * Update cross refs in api and operations * First pass at updating conf refs * Fix remaining cross refs * Convert to relative links for cloud * Fix URL sytnax --------- Signed-off-by: Jack Baldry <[email protected]> Co-authored-by: Jack Baldry <[email protected]>
grafana · Aug 22, 2023 · 0cd4d26 · 0cd4d26
1 parent 492e6cd
commit 0cd4d26
Show file tree

Hide file tree

Showing 18 changed files with 213 additions and 93 deletions.
diff --git a/.github/workflows/check_docs.yml b/.github/workflows/check_docs.yml
@@ -7,5 +7,9 @@ jobs:
     - name: "Check out code"
       uses: "actions/checkout@v3"
     - name: "Build technical documentation"
-      run: |
-        docker run -v ${PWD}/docs/sources:/hugo/content/docs/agent/latest -e HUGO_REFLINKSERRORLEVEL=ERROR --rm grafana/docs-base:latest /bin/bash -c 'make hugo'
+      run: >
+        docker run
+        --volume "${PWD}/docs/sources:/hugo/content/docs/agent/latest"
+        --env HUGO_REFLINKSERRORLEVEL=ERROR
+        --rm grafana/docs-base:latest
+        /bin/bash -c 'echo -e "---\\nredirectURL: /docs/agent/latest/\\ntype: redirect\\nversioned: true\\n---\\n" > /hugo/content/docs/agent/_index.md && make hugo'
diff --git a/docs/sources/flow/release-notes.md b/docs/sources/flow/release-notes.md
@@ -1,5 +1,5 @@
 ---
-canonical: https://grafana.com/docs/agent/latest/flow/upgrade-guide/
+canonical: https://grafana.com/docs/agent/latest/flow/release-notes/
 description: Release notes for Grafana Agent flow mode
 title: Release notes for Grafana Agentflow mode
 menuTitle: Release notes

diff --git a/docs/sources/static/_index.md b/docs/sources/static/_index.md
@@ -19,7 +19,7 @@ Static mode is composed of different _subsystems_:
   traces and forwarding them to Grafana Tempo or any OpenTelemetry-compatible
   endpoint.
 
-Static mode is [configured][] with a YAML file.
+Static mode is [configured][configure] with a YAML file.
 
 Static mode works with:
 
@@ -33,10 +33,6 @@ use Grafana Agent to meet your goals.
 You can [set up][] and [configure][] Grafana Agent in static mode manually, or
 you can follow the common workflows described in this topic.
 
-[set up]: {{< relref "./set-up" >}}
-[configure]: {{< relref "./configuration/" >}}
-[configured]: {{< relref "./configuration/" >}}
-
 ## Topics
 
 ### Static mode Grafana Agent for Grafana Cloud integrations
@@ -67,13 +63,11 @@ Grafana Cloud integration workflows and the Kubernetes Monitoring solution are t
 
 | Topic | Description |
 |---|---|
-| [Install or uninstall Grafana Agent][] | Install or uninstall Grafana Agent. |
+| [Install or uninstall Grafana Agent][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-troubleshoot-windows/) | Troubleshoot common errors when executing the Grafana Agent installation script on Windows.  |
 
-[Install or uninstall Grafana Agent]: {{< relref "./set-up/install/" >}}
-
 ### Use Grafana Agent to send logs to Grafana Loki
 
 Logs are included when you [set up a Cloud integration](/docs/grafana-cloud/data-configuration/integrations/install-and-manage-integrations) but you can take a more hands-on approach with the following guide.
@@ -88,3 +82,12 @@ 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 %}}
diff --git a/docs/sources/static/api/_index.md b/docs/sources/static/api/_index.md
@@ -19,10 +19,12 @@ API endpoints are stable unless otherwise noted.
 
 ## Config management API (Beta)
 
-Grafana Agent exposes a config management REST API for managing instance configurations when it is running in [scraping service mode]({{< relref "../configuration/scraping-service/" >}}).
+Grafana Agent exposes a config management REST API for managing instance configurations when it is running in [scraping service mode][scrape].
 
-(Note that scraping service mode is a requirement for the config management
-API, however this is not a prerequisite for the Agent API or Ready/Healthy API)
+{{% admonition type="note" %}}
+The scraping service mode is a requirement for the config management
+API, however this is not a prerequisite for the Agent API or Ready/Healthy API.
+{{% /admonition %}}
 
 The following endpoints are exposed:
 
@@ -116,17 +118,18 @@ with the same name already exists, then it will be completely overwritten.
 URL-encoded names are stored in decoded form. e.g., `hello%2Fworld` will
 represent the config named `hello/world`.
 
-The request body passed to this endpoint must match the format of
-[metrics_instance_config]({{< relref "../configuration/metrics-config" >}})
+The request body passed to this endpoint must match the format of [metrics_instance_config][metrics]
 defined in the Configuration Reference. The name field of the configuration is
 ignored and the name in the URL takes precedence. The request body must be
 formatted as YAML.
 
-**WARNING**: By default, all instance configuration files that read
+{{% admonition type="warning" %}}
+By default, all instance configuration files that read
 credentials from a file on disk will be rejected. This prevents malicious users
 from reading the contents of arbitrary files as passwords and sending their
 contents to fake remote_write endpoints. To change the behavior, set
 `dangerous_allow_reading_files` to true in the `scraping_service` block.
+{{% /admonition %}}
 
 Status code: 201 with a new config, 200 on updated config.
 Response on success:
@@ -166,7 +169,10 @@ Response on success:
 ```
 GET /agent/api/v1/metrics/instances
 ```
-*note:* deprecated alias is `/agent/api/v1/instances`
+
+{{% admonition type="note" %}}
+The deprecated alias is `/agent/api/v1/instances`
+{{% /admonition %}}
 
 Status code: 200 on success.
 Response on success:
@@ -185,7 +191,10 @@ Response on success:
 ```
 GET /agent/api/v1/metrics/targets
 ```
-*note:* deprecated alias is `/agent/api/v1/targets`
+
+{{% admonition type="note" %}}
+The deprecated alias is `/agent/api/v1/targets`
+{{% /admonition %}}
 
 This endpoint collects all metrics subsystem targets known to the Agent across all
 running instances. Only targets being scraped from the local Agent will be returned. If
@@ -396,7 +405,7 @@ A support bundle contains the following data:
 ## Integrations API (Experimental)
 
 > **WARNING**: This API is currently only available when the experimental
-> [integrations revamp]({{< relref "../configuration/integrations/integrations-next" >}})
+> [integrations revamp][integrations]
 > is enabled. Both the revamp and this API are subject to change while they
 > are still experimental.
 
@@ -407,8 +416,7 @@ GET /agent/api/v1/metrics/integrations/sd
 ```
 
 This endpoint returns all running metrics-based integrations. It conforms to
-the Prometheus [http_sd_config
-API](https://prometheus.io/docs/prometheus/2.45/configuration/configuration/#http_sd_config).
+the Prometheus [http_sd_config API](https://prometheus.io/docs/prometheus/2.45/configuration/configuration/#http_sd_config).
 Targets include integrations regardless of autoscrape being enabled; this
 allows for manually configuring scrape jobs to collect metrics from an
 integration running on an external agent.
@@ -508,3 +516,12 @@ Response:
 ```
 Agent is Healthy.
 ```
+
+{{% docs/reference %}}
+[scrape]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/static/configuration/scraping-service"
+[scrape]: "/docs/grafana-cloud/ -> ../configuration/scraping-service
+[metrics]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/static/configuration/metrics-config"
+[metrics]: "/docs/grafana-cloud/ -> ../configuration/metrics-config"
+[integrations]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/static/configuration/integrations/integrations-next"
+[integrations]: "/docs/grafana-cloud/ -> ../configuration/integrations/integrations-next"
+{{% /docs/reference %}}
diff --git a/docs/sources/static/configuration/_index.md b/docs/sources/static/configuration/_index.md
@@ -11,19 +11,19 @@ weight: 300
 The configuration of static mode is split across two places:
 
 * A YAML file
-* [Command-line flags]({{< relref "./flags.md" >}})
+* [Command-line flags][flags]
 
 The YAML file is used to configure settings which are dynamic and can be
 changed at runtime. The command-line flags then configure things which cannot
 change at runtime, such as the listen port for the HTTP server.
 
 This file describes the YAML configuration, which is usually in a file named `config.yaml`.
 
-- [server_config]({{< relref "./server-config" >}})
-- [metrics_config]({{< relref "./metrics-config" >}})
-- [logs_config]({{< relref "./logs-config.md" >}})
-- [traces_config]({{< relref "./traces-config" >}})
-- [integrations_config]({{< relref "./integrations/_index.md" >}})
+- [server_config][server]
+- [metrics_config][metrics]
+- [logs_config][logs]
+- [traces_config][traces]
+- [integrations_config][integrations]
 
 The configuration of Grafana Agent is "stable," but subject to breaking changes
 as individual features change. Breaking changes to configuration will be
@@ -76,8 +76,7 @@ which may be slightly unexpected.
 
 ## Reloading (beta)
 
-The configuration file can be reloaded at runtime. Read the [API
-documentation]({{< relref "../api#reload-configuration-file-beta" >}}) for more information.
+The configuration file can be reloaded at runtime. Read the [API documentation][api] for more information.
 
 This functionality is in beta, and may have issues. Please open GitHub issues
 for any problems you encounter.
@@ -135,4 +134,23 @@ The following flags will configure basic auth for requests made to HTTP/S remote
 - `-config.url.basic-auth-user <user>`: the basic auth username
 - `-config.url.basic-auth-password-file <file>`: path to a file containing the basic auth password
 
-Note that this beta feature is subject to change in future releases.
+{{% admonition type="note" %}}
+This beta feature is subject to change in future releases.
+{{% /admonition %}}
+
+{{% docs/reference %}}
+[flags]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/static/configuration/flags"
+[flags]: "/docs/grafana-cloud/ -> ./flags"
+[server]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/static/configuration/server-config"
+[server]: "/docs/grafana-cloud/ -> ./server-config"
+[metrics]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/static/configuration/metrics-config"
+[metrics]: "/docs/grafana-cloud/ -> ./metrics-config"
+[logs]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/static/configuration/logs-config"
+[logs]: "/docs/grafana-cloud/ -> ./logs-config"
+[traces]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/static/configuration/traces-config"
+[traces]: "/docs/grafana-cloud/ -> ./traces-config"
+[integrations]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/static/configuration/integrations"
+[integrations]: "/docs/grafana-cloud/ -> ./integrations"
+[api]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/static/api#reload-configuration-file-beta"
+[api]: "/docs/grafana-cloud/ -> ../api#reload-configuration-file-beta"
+{{% /docs/reference %}}
diff --git a/docs/sources/static/configuration/create-config-file.md b/docs/sources/static/configuration/create-config-file.md
@@ -61,8 +61,7 @@ the Grafana Agent is running on. This label helps to uniquely identify the
 source of metrics if you are running multiple Grafana Agents across multiple
 machines.
 
-Full configuration options can be found in the
-[configuration reference]({{< relref "../configuration/_index.md" >}}).
+Full configuration options can be found in the [configuration reference][configure].
 
 ## Prometheus config/migrating from Prometheus
 
@@ -107,7 +106,7 @@ metrics:
 ```
 
 Like with integrations, full configuration options can be found in the
-[configuration]({{< relref "../configuration/_index.md" >}}).
+[configuration][configure].
 
 ## Loki Config/Migrating from Promtail
 
@@ -183,3 +182,8 @@ integrations:
   node_exporter:
     enabled: true
 ```
+
+{{% docs/reference %}}
+[configure]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/static/configuration"
+[configure]: "/docs/grafana-cloud/ -> ./configuration"
+{{% /docs/reference %}}
diff --git a/docs/sources/static/configuration/flags.md b/docs/sources/static/configuration/flags.md
@@ -30,10 +30,10 @@ names to enable.
 
 Valid feature names are:
 
-* `remote-configs`: Enable [retrieving]({{< relref "./_index.md#remote-configuration-experimental" >}}) config files over HTTP/HTTPS
-* `integrations-next`: Enable [revamp]({{< relref "./integrations/integrations-next/" >}}) of the integrations subsystem
+* `remote-configs`: Enable [retrieving][retrieving] config files over HTTP/HTTPS
+* `integrations-next`: Enable [revamp][revamp] of the integrations subsystem
 * `extra-scrape-metrics`: When enabled, additional time series  are exposed for each metrics instance scrape. See [Extra scrape metrics](https://prometheus.io/docs/prometheus/2.45/feature_flags/#extra-scrape-metrics).
-* `agent-management`: Enable support for [agent management]({{< relref "./agent-management" >}}).
+* `agent-management`: Enable support for [agent management][management].
 
 ## Report information usage
 
@@ -142,3 +142,12 @@ YAML configuration when the `-server.http.tls-enabled` flag is used.
 ## Metrics
 
 * `-metrics.wal-directory`: Directory to store the metrics Write-Ahead Log in
+
+{{% docs/reference %}}
+[retrieving]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/static/configuration#remote-configuration-experimental"
+[retrieving]: "/docs/grafana-cloud/ -> ./configuration#remote-configuration-experimental"
+[revamp]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/static/configuration/integrations/integrations-next/"
+[revamp]: "/docs/grafana-cloud/ -> ./integrations/integrations-next/"
+[management]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/static/configuration/agent-management"
+[management]: "/docs/grafana-cloud/ -> ./agent-management"
+{{% /docs/reference %}}
diff --git a/docs/sources/static/configuration/metrics-config.md b/docs/sources/static/configuration/metrics-config.md
@@ -65,8 +65,7 @@ configs:
 
 ## scraping_service_config
 
-The `scraping_service` block configures the
-[scraping service]({{< relref "scraping-service/" >}}), an operational
+The `scraping_service` block configures the [scraping service][scrape], an operational
 mode where configurations are stored centrally in a KV store and a cluster of
 agents distributes discovery and scrape load between nodes.
 
@@ -335,3 +334,8 @@ remote_write:
 > * [`relabel_config`](https://prometheus.io/docs/prometheus/2.45/configuration/configuration/#relabel_config)
 > * [`scrape_config`](https://prometheus.io/docs/prometheus/2.45/configuration/configuration/#scrape_config)
 > * [`remote_write`](https://prometheus.io/docs/prometheus/2.45/configuration/configuration/#remote_write)
+
+{{% docs/reference %}}
+[scrape]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/static/configuration/scraping-service"
+[scrape]: "/docs/grafana-cloud/ -> ./scraping-service"
+{{% /docs/reference %}}
diff --git a/docs/sources/static/configuration/scraping-service.md b/docs/sources/static/configuration/scraping-service.md
@@ -14,7 +14,7 @@ that allows for clustering a set of Agent processes and distributing scrape load
 across them.
 
 Determining what to scrape is done by writing instance configuration files to an
-[API]({{< relref "../api" >}}), which then stores the configuration files in a KV store backend.
+[API][api], which then stores the configuration files in a KV store backend.
 All agents in the cluster **must** use the same KV store so they see the same set
 of config files.
 
@@ -44,7 +44,7 @@ remote_write:
 
 The full set of supported options for an instance configuration file is
 available in the
-[`metrics-config.md` file]({{< relref "metrics-config" >}}).
+[`metrics-config.md` file][metrics].
 
 Having multiple instance configuration files is necessary for sharding; each
 config file is distributed to a particular agent on the cluster based on the
@@ -168,3 +168,10 @@ Entries in the API not in the synced directory will be deleted.
 container with the `grafana/agentctl` image. Tanka configurations that
 utilize `grafana/agentctl` and sync a set of configurations to the API
 are planned for the future.
+
+{{% docs/reference %}}
+[api]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/static/api"
+[api]: "/docs/grafana-cloud/ -> ../api"
+[metrics]: "/docs/agent/ -> /docs/agent/<AGENT VERSION>/static/configuration/metrics-config"
+[metrics]: "/docs/grafana-cloud/ -> ./metrics-config"
+{{% /docs/reference %}}
diff --git a/docs/sources/static/configuration/traces-config.md b/docs/sources/static/configuration/traces-config.md
@@ -14,9 +14,11 @@ configures its own tracing pipeline. Having multiple configs allows you to
 configure multiple distinct pipelines, each of which collects spans and sends
 them to a different location.
 
-Note that if using multiple configs, you must manually set port numbers for
+{{% admonition type="note" %}}
+If you are using multiple configs, you must manually set port numbers for
 each receiver, otherwise they will all try to use the same port and fail to
 start.
+{{% /admonition %}}
 
 ```yaml
 configs:
@@ -429,9 +431,8 @@ jaeger_remote_sampling:
   [ - <jaeger_remote_sampling> ... ]
 ```
 
-> **Note:** More information on the following types can be found on the
-> documentation for their respective projects:
->
+More information on the following types can be found on the documentation for their respective projects:
+
 * [`attributes.config`: OpenTelemetry-Collector](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/v0.80.0/processor/attributesprocessor)
 * [`batch.config`: OpenTelemetry-Collector](https://github.com/open-telemetry/opentelemetry-collector/tree/v0.80.0/processor/batchprocessor)
 * [`otlpexporter.sending_queue`: OpenTelemetry-Collector](https://github.com/open-telemetry/opentelemetry-collector/tree/v0.80.0/exporter/otlpexporter)