Refactoring layout spelling syntax spacing

docs/sources/flow/getting-started/configure-agent-clustering.md

@@ -13,9 +13,7 @@ weight: 400
 
 # Configure {{< param "PRODUCT_NAME" >}} clustering in an existing installation
 
-You can configure {{< param "PRODUCT_NAME" >}} to run with [clustering][] so that
-individual {{< param "PRODUCT_ROOT_NAME" >}}s can work together for workload distribution and high
-availability.
+You can configure {{< param "PRODUCT_NAME" >}} to run with [clustering][] so that individual {{< param "PRODUCT_ROOT_NAME" >}}s can work together for workload distribution and high availability.
 
 > **Note:** Clustering is a [beta][] feature. Beta features are subject to breaking
 > changes and may be replaced with equivalent functionality that covers the same use case.
@@ -24,20 +22,17 @@ This topic describes how to add clustering to an existing installation.
 
 ## Configure {{< param "PRODUCT_NAME" >}} clustering with Helm Chart
 
-This section guides you through enabling clustering when {{< param "PRODUCT_NAME" >}} is
-installed on Kubernetes using the {{< param "PRODUCT_ROOT_NAME" >}} [Helm chart][install-helm].
+This section guides you through enabling clustering when {{< param "PRODUCT_NAME" >}} is installed on Kubernetes using the {{< param "PRODUCT_ROOT_NAME" >}} [Helm chart][install-helm].
 
 ### Before you begin
 
-- Ensure that your `values.yaml` file has `controller.type` set to
-  `statefulset`.
+- Ensure that your `values.yaml` file has `controller.type` set to `statefulset`.
 
 ### Steps
 
 To configure clustering:
 
-1. Amend your existing values.yaml file to add `clustering.enabled=true` inside
-   of the `agent` block:
+1. Amend your existing `values.yaml` file to add `clustering.enabled=true` inside of the `agent` block.
 
    ```yaml
    agent:

docs/sources/flow/getting-started/distribute-prometheus-scrape-load.md

@@ -13,10 +13,8 @@ weight: 500
 
 # Distribute Prometheus metrics scrape load
 
-A good predictor for the size of an {{< param "PRODUCT_NAME" >}} deployment is the number of
-Prometheus targets each {{< param "PRODUCT_ROOT_NAME" >}} scrapes. [Clustering][] with target
-auto-distribution allows a fleet of {{< param "PRODUCT_ROOT_NAME" >}}s to work together to dynamically
-distribute their scrape load, providing high-availability.
+A good predictor for the size of an {{< param "PRODUCT_NAME" >}} deployment is the number of Prometheus targets each {{< param "PRODUCT_ROOT_NAME" >}} scrapes.
+[Clustering][] with target auto-distribution allows a fleet of {{< param "PRODUCT_ROOT_NAME" >}}s to work together to dynamically distribute their scrape load, providing high-availability.
 
 > **Note:** Clustering is a [beta][] feature. Beta features are subject to breaking
 > changes and may be replaced with equivalent functionality that covers the same use case.
@@ -32,8 +30,7 @@ distribute their scrape load, providing high-availability.
 
 To distribute Prometheus metrics scrape load with clustering:
 
-1. Add the following block to all `prometheus.scrape` components which
-   should use auto-distribution:
+1. Add the following block to all `prometheus.scrape` components which should use auto-distribution:
 
    ```river
    clustering {
@@ -45,8 +42,7 @@ To distribute Prometheus metrics scrape load with clustering:
 
 1. Validate that auto-distribution is functioning:
 
-   1. Using the {{< param "PRODUCT_ROOT_NAME" >}} [UI][] on each {{< param "PRODUCT_ROOT_NAME" >}}, navigate to the details page for one of
-      the `prometheus.scrape` components you modified.
+   1. Using the {{< param "PRODUCT_ROOT_NAME" >}} [UI][] on each {{< param "PRODUCT_ROOT_NAME" >}}, navigate to the details page for one of the `prometheus.scrape` components you modified.
 
    1. Compare the Debug Info sections between two different {{< param "PRODUCT_ROOT_NAME" >}} to ensure that they're not scraping the same sets of targets.
 

docs/sources/flow/getting-started/migrating-from-operator.md

@@ -85,7 +85,7 @@ remote.kubernetes.secret "credentials" {
 
 prometheus.remote_write "primary" {
     endpoint {
-        url = "https://PROMETHEUS_URL/api/v1/push"
+        url = "https://<PROMETHEUS_URL>/api/v1/push"
         basic_auth {
             username = nonsensitive(remote.kubernetes.secret.credentials.data["username"])
             password = remote.kubernetes.secret.credentials.data["password"]
@@ -111,7 +111,9 @@ prometheus.operator.servicemonitors "primary" {
 
 ```
 
-You will need to replace `PROMETHEUS_URL` with the actual endpoint you want to send metrics to.
+Replace the following:
+
+- _`<PROMETHEUS_URL>`_: The endpoint you want to send metrics to.
 
 This configuration will discover all `PodMonitor`, `ServiceMonitor`, and `Probe` resources in your cluster that match our label selector `instance=primary`.
 It will then scrape metrics from their targets and forward them to your remote write endpoint.
@@ -260,7 +262,9 @@ loki.write "loki" {
 }
 ```
 
-You will need to replace `LOKI_URL` with the actual endpoint of your Loki instance.
+Replace the following:
+
+- _`<LOKI_URL>`_: The endpoint of your Loki instance.
 
 The logging subsystem is very powerful and has many options for processing logs. For further details see the [component documentation][].
 

docs/sources/flow/getting-started/migrating-from-prometheus.md

@@ -33,40 +33,37 @@ This topic describes how to:
 
 ## Convert a Prometheus configuration
 
-To fully migrate your configuration from [Prometheus] to {{< param "PRODUCT_NAME" >}},
-you must convert your Prometheus configuration into a {{< param "PRODUCT_NAME" >}} configuration.
-This conversion will enable you to take full advantage of the many
-additional features available in {{< param "PRODUCT_NAME" >}}.
+To fully migrate your configuration from [Prometheus] to {{< param "PRODUCT_NAME" >}}, you must convert your Prometheus configuration into a {{< param "PRODUCT_NAME" >}} configuration.
+This conversion will enable you to take full advantage of the many additional features available in {{< param "PRODUCT_NAME" >}}.
 
 > In this task, we will use the [convert][] CLI command to output a flow
 > configuration from a Prometheus configuration.
 
-1. Open a terminal window and run the following command:
+1. Open a terminal window and run the following command.
 
    {{< code >}}
 
    ```static-binary
-   AGENT_MODE=flow grafana-agent convert --source-format=prometheus --output=OUTPUT_CONFIG_PATH INPUT_CONFIG_PATH
+   AGENT_MODE=flow grafana-agent convert --source-format=prometheus --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>
    ```
 
    ```flow-binary
-   grafana-agent-flow convert --source-format=prometheus --output=OUTPUT_CONFIG_PATH INPUT_CONFIG_PATH
+   grafana-agent-flow convert --source-format=prometheus --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>
    ```
 
    {{< /code >}}
 
-    Replace the following:
-      * `INPUT_CONFIG_PATH`: The full path to the Prometheus configuration.
-      * `OUTPUT_CONFIG_PATH`: The full path to output the {{< param "PRODUCT_NAME" >}} configuration.
+   Replace the following:
 
-1. [Start][] {{< param "PRODUCT_NAME" >}} using the new flow configuration from `OUTPUT_CONFIG_PATH`:
+   - _`<INPUT_CONFIG_PATH>`_: The full path to the Prometheus configuration.
+   - _`<OUTPUT_CONFIG_PATH>`_: The full path to output the {{< param "PRODUCT_NAME" >}} configuration.
+
+1. [Start][] {{< param "PRODUCT_NAME" >}} using the new flow configuration from _`<OUTPUT_CONFIG_PATH>`_:
 
 ### Debugging
 
-1. If the convert command can't convert a Prometheus configuration,
-   diagnostic information is sent to `stderr`. You can bypass
-   any non-critical issues and output the flow configuration using a
-   best-effort conversion by including the `--bypass-errors` flag.
+1. If the convert command can't convert a Prometheus configuration, diagnostic information is sent to `stderr`.\
+   You can bypass any non-critical issues and output the flow configuration using a best-effort conversion by including the `--bypass-errors` flag.
 
     {{% admonition type="caution" %}}
     If you bypass the errors, the behavior of the converted configuration may not match the original Prometheus configuration.
@@ -76,32 +73,41 @@ additional features available in {{< param "PRODUCT_NAME" >}}.
    {{< code >}}
 
    ```static-binary
-   AGENT_MODE=flow grafana-agent convert --source-format=prometheus --bypass-errors --output=OUTPUT_CONFIG_PATH INPUT_CONFIG_PATH
+   AGENT_MODE=flow grafana-agent convert --source-format=prometheus --bypass-errors --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>
    ```
 
    ```flow-binary
-   grafana-agent-flow convert --source-format=prometheus --bypass-errors --output=OUTPUT_CONFIG_PATH INPUT_CONFIG_PATH
+   grafana-agent-flow convert --source-format=prometheus --bypass-errors --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>
    ```
 
    {{< /code >}}
 
+   Replace the following:
+
+   - _`<INPUT_CONFIG_PATH>`_: The full path to the Prometheus configuration.
+   - _`<OUTPUT_CONFIG_PATH>`_: The full path to output the {{< param "PRODUCT_NAME" >}} configuration.
+
 1. You can also output a diagnostic report by including the `--report` flag.
 
    {{< code >}}
 
    ```static-binary
-   AGENT_MODE=flow grafana-agent convert --source-format=prometheus --report=OUTPUT_REPORT_PATH --output=OUTPUT_CONFIG_PATH INPUT_CONFIG_PATH
+   AGENT_MODE=flow grafana-agent convert --source-format=prometheus --report=<OUTPUT_REPORT_PATH> --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>
    ```
 
    ```flow-binary
-   grafana-agent-flow convert --source-format=prometheus --report=OUTPUT_REPORT_PATH --output=OUTPUT_CONFIG_PATH INPUT_CONFIG_PATH
+   grafana-agent-flow convert --source-format=prometheus --report=<OUTPUT_REPORT_PATH> --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>
    ```
 
    {{< /code >}}
 
-    * Replace `OUTPUT_REPORT_PATH` with the output path for the report.
+   Replace the following:
 
-    Using the [example](#example) Prometheus configuration below, the diagnostic report provides the following information:
+   - _`<INPUT_CONFIG_PATH>`_: The full path to the Prometheus configuration.
+   - _`<OUTPUT_CONFIG_PATH>`_: The full path to output the {{< param "PRODUCT_NAME" >}} configuration.
+   - _`<OUTPUT_REPORT_PATH>`_: The output path for the report.
+
+    Using the [example][] Prometheus configuration below, the diagnostic report provides the following information:
 
     ```plaintext
     (Info) Converted scrape_configs job_name "prometheus" into...
@@ -119,34 +125,28 @@ This allows you to try {{< param "PRODUCT_NAME" >}} without modifying your exist
 > In this task, we will use the [run][] CLI command to run {{< param "PRODUCT_NAME" >}}
 > using a Prometheus configuration.
 
-[Start][] {{< param "PRODUCT_NAME" >}} and include the command line flag
-   `--config.format=prometheus`. Your configuration file must be a valid
-   Prometheus configuration file rather than a {{< param "PRODUCT_NAME" >}} configuration file.
+[Start][] {{< param "PRODUCT_NAME" >}} and include the command line flag `--config.format=prometheus`.
+Your configuration file must be a valid Prometheus configuration file rather than a {{< param "PRODUCT_NAME" >}} configuration file.
 
 ### Debugging
 
-1. You can follow the convert CLI command [debugging][] instructions to
-   generate a diagnostic report.
+1. You can follow the convert CLI command [debugging][] instructions to generate a diagnostic report.
 
 1. Refer to the {{< param "PRODUCT_NAME" >}} [Debugging][DebuggingUI] for more information about a running {{< param "PRODUCT_NAME" >}}.
 
-1. If your Prometheus configuration can't be converted and
-    loaded directly into {{< param "PRODUCT_NAME" >}}, diagnostic information
-    is sent to `stderr`. You can bypass any non-critical issues
-    and start the Agent by including the
-   `--config.bypass-conversion-errors` flag in addition to
-   `--config.format=prometheus`.
+1. If your Prometheus configuration can't be converted and loaded directly into {{< param "PRODUCT_NAME" >}}, diagnostic information is sent to `stderr`.
+   You can bypass any non-critical issues and start the Agent by including the `--config.bypass-conversion-errors` flag in addition to `--config.format=prometheus`.
 
-    {{% admonition type="caution" %}}
-    If you bypass the errors, the behavior of the converted configuration may not match the original Prometheus configuration.
-    Do not use this flag in a production environment.
-    {{% /admonition %}}
+   {{% admonition type="caution" %}}
+   If you bypass the errors, the behavior of the converted configuration may not match the original Prometheus configuration.
+   Do not use this flag in a production environment.
+   {{% /admonition %}}
 
 ## Example
 
 This example demonstrates converting a Prometheus configuration file to a {{< param "PRODUCT_NAME" >}} configuration file.
 
-The following Prometheus configuration file provides the input for the conversion:
+The following Prometheus configuration file provides the input for the conversion.
 
 ```yaml
 global:
@@ -161,24 +161,29 @@ remote_write:
   - name: "grafana-cloud"
     url: "https://prometheus-us-central1.grafana.net/api/prom/push"
     basic_auth:
-      username: USERNAME
-      password: PASSWORD
+      username: <USERNAME>
+      password: <PASSWORD>
 ```
 
 The convert command takes the YAML file as input and outputs a [River][] file.
 
 {{< code >}}
 
 ```static-binary
-AGENT_MODE=flow grafana-agent convert --source-format=prometheus --output=OUTPUT_CONFIG_PATH INPUT_CONFIG_PATH
+AGENT_MODE=flow grafana-agent convert --source-format=prometheus --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>
 ```
 
 ```flow-binary
-grafana-agent-flow convert --source-format=prometheus --output=OUTPUT_CONFIG_PATH INPUT_CONFIG_PATH
+grafana-agent-flow convert --source-format=prometheus --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>
 ```
 
 {{< /code >}}
 
+Replace the following:
+
+- _`<INPUT_CONFIG_PATH>`_: The full path to the Prometheus configuration.
+- _`<OUTPUT_CONFIG_PATH>`_: The full path to output the {{< param "PRODUCT_NAME" >}} configuration.
+
 The new flow configuration file looks like this:
 
 ```river
@@ -216,29 +221,23 @@ prometheus.remote_write "default" {
 
 ## Limitations
 
-Configuration conversion is done on a best-effort basis. {{< param "PRODUCT_ROOT_NAME" >}} will issue
-warnings or errors where the conversion cannot be performed.
+Configuration conversion is done on a best-effort basis. {{< param "PRODUCT_ROOT_NAME" >}} will issue warnings or errors where the conversion can't be performed.
 
-Once the configuration is converted, we recommend that you review
-the {{< param "PRODUCT_NAME" >}} configuration file created and verify that it is correct
-before starting to use it in a production environment.
+After the configuration is converted, we recommend that you review the {{< param "PRODUCT_NAME" >}} configuration file created and verify that it's correct before starting to use it in a production environment.
 
 Furthermore, we recommend that you review the following checklist:
 
-* The following configurations are not available for conversion to {{< param "PRODUCT_NAME" >}}:
-  `rule_files`, `alerting`, `remote_read`, `storage`, and `tracing`. Any
-  additional unsupported features are returned as errors during conversion.
-* Check if you are using any extra command line arguments with Prometheus that
-  are not present in your configuration file. For example, `--web.listen-address`.
-* Metamonitoring metrics exposed by {{< param "PRODUCT_NAME" >}} usually match Prometheus
-  metamonitoring metrics but will use a different name. Make sure that you use
-  the new metric names, for example, in your alerts and dashboards queries.
-* The logs produced by {{< param "PRODUCT_NAME" >}} differ from those
-  produced by Prometheus.
+* The following configurations aren't available for conversion to {{< param "PRODUCT_NAME" >}}: `rule_files`, `alerting`, `remote_read`, `storage`, and `tracing`.
+  Any additional unsupported features are returned as errors during conversion.
+* Check if you are using any extra command line arguments with Prometheus that are not present in your configuration file. For example, `--web.listen-address`.
+* Metamonitoring metrics exposed by {{< param "PRODUCT_NAME" >}} usually match Prometheus metamonitoring metrics but will use a different name.
+  Make sure that you use the new metric names, for example, in your alerts and dashboards queries.
+* The logs produced by {{< param "PRODUCT_NAME" >}} differ from those produced by Prometheus.
 * {{< param "PRODUCT_ROOT_NAME" >}} exposes the {{< param "PRODUCT_NAME" >}} [UI][].
 
 [Prometheus]: https://prometheus.io/docs/prometheus/latest/configuration/configuration/
 [debugging]: #debugging
+[example]: #example
 
 {{% docs/reference %}}
 [prometheus.scrape]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/components/prometheus.scrape.md"