From f8bf82a1e19ae3b05b8c1d6c5ecd48711ce7c120 Mon Sep 17 00:00:00 2001
From: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com>
Date: Wed, 22 Jan 2025 10:37:56 -0800
Subject: [PATCH] Update and lint discovery.azure to discovery.dockerswarm
 (#2403)

* Update discover azure and consul topics

* Update dogitalocean, dns, and docker topics

* Additional style cleanup

* Linting updates and edits

* Syntax and mardown cleanup

* Minor updates from review

* Add missing descriptions and add OSS badge

* Fix a typo and two sentences

* Simplify link definitions

* Fix typo and remove duplicated frontmatter

* Fix literal string quoting in examples

(cherry picked from commit 63ba0160be3b9740cca117f0c27621e2f5f35471)
---
 docs/sources/_index.md                        |   2 +-
 docs/sources/_index.md.t                      |   2 +-
 .../components/discovery/discovery.azure.md   | 106 ++++----
 .../components/discovery/discovery.consul.md  | 112 ++++----
 .../discovery/discovery.consulagent.md        |  95 +++----
 .../discovery/discovery.digitalocean.md       |  50 ++--
 .../components/discovery/discovery.dns.md     |  38 +--
 .../components/discovery/discovery.docker.md  | 133 +++++-----
 .../discovery/discovery.dockerswarm.md        | 241 +++++++++---------
 9 files changed, 412 insertions(+), 367 deletions(-)

diff --git a/docs/sources/_index.md b/docs/sources/_index.md
index 58be26d42d..ac38662550 100644
--- a/docs/sources/_index.md
+++ b/docs/sources/_index.md
@@ -1,7 +1,7 @@
 ---
 canonical: https://grafana.com/docs/alloy/latest/
 title: Grafana Alloy
-description: Grafana Alloy is a a vendor-neutral distribution of the OTel Collector
+description: Grafana Alloy is a vendor-neutral distribution of the OTel Collector
 weight: 350
 cascade:
   ALLOY_RELEASE: v1.3.4
diff --git a/docs/sources/_index.md.t b/docs/sources/_index.md.t
index aa44e44df2..61500df70f 100644
--- a/docs/sources/_index.md.t
+++ b/docs/sources/_index.md.t
@@ -1,7 +1,7 @@
 ---
 canonical: https://grafana.com/docs/alloy/latest/
 title: Grafana Alloy
-description: Grafana Alloy is a a vendor-neutral distribution of the OTel Collector
+description: Grafana Alloy is a vendor-neutral distribution of the OTel Collector
 weight: 350
 cascade:
   ALLOY_RELEASE: $ALLOY_VERSION
diff --git a/docs/sources/reference/components/discovery/discovery.azure.md b/docs/sources/reference/components/discovery/discovery.azure.md
index 72c5123017..ff9621d9b3 100644
--- a/docs/sources/reference/components/discovery/discovery.azure.md
+++ b/docs/sources/reference/components/discovery/discovery.azure.md
@@ -21,56 +21,60 @@ discovery.azure "<LABEL>" {
 
 ## Arguments
 
-The following arguments are supported:
+You can use the following arguments with `discovery.azure`:
 
 Name                     | Type                | Description                                                                                      | Default              | Required
 -------------------------|---------------------|--------------------------------------------------------------------------------------------------|----------------------|---------
+`enable_http2`           | `bool`              | Whether HTTP2 is supported for requests.                                                         | `true`               | no
 `environment`            | `string`            | Azure environment.                                                                               | `"AzurePublicCloud"` | no
-`port`                   | `number`            | Port to be appended to the `__address__` label for each target.                                  | `80`                 | no
-`subscription_id`        | `string`            | Azure subscription ID.                                                                           |                      | no
-`refresh_interval`       | `duration`          | Interval at which to refresh the list of targets.                                                | `5m`                 | no
-`proxy_url`              | `string`            | HTTP proxy to send requests through.                                                             |                      | no
+`follow_redirects`       | `bool`              | Whether redirects returned by the server should be followed.                                     | `true`               | no
 `no_proxy`               | `string`            | Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying. |                      | no
-`proxy_from_environment` | `bool`              | Use the proxy URL indicated by environment variables.                                            | `false`              | no
+`port`                   | `number`            | The port appended to the `__address__` label for each target.                                    | `80`                 | no
 `proxy_connect_header`   | `map(list(secret))` | Specifies headers to send to proxies during CONNECT requests.                                    |                      | no
-`follow_redirects`       | `bool`              | Whether redirects returned by the server should be followed.                                     | `true`               | no
-`enable_http2`           | `bool`              | Whether HTTP2 is supported for requests.                                                         | `true`               | no
+`proxy_from_environment` | `bool`              | Use the proxy URL indicated by environment variables.                                            | `false`              | no
+`proxy_url`              | `string`            | HTTP proxy to send requests through.                                                             |                      | no
+`refresh_interval`       | `duration`          | Interval at which to refresh the list of targets.                                                | `5m`                 | no
+`subscription_id`        | `string`            | Azure subscription ID.                                                                           |                      | no
 
 {{< docs/shared lookup="reference/components/http-client-proxy-config-description.md" source="alloy" version="<ALLOY_VERSION>" >}}
 
 ## Blocks
-The following blocks are supported inside the definition of
-`discovery.azure`:
 
-Hierarchy        | Block                | Description                                      | Required
------------------|----------------------|--------------------------------------------------|---------
-oauth            | [oauth][]            | OAuth configuration for Azure API.               | no
-managed_identity | [managed_identity][] | Managed Identity configuration for Azure API.    | no
-tls_config       | [tls_config][]       | TLS configuration for requests to the Azure API. | no
+You can use the following blocks with `discovery.azure`:
 
-Exactly one of the `oauth` or `managed_identity` blocks must be specified.
+Block                | Description                                      | Required
+---------------------|--------------------------------------------------|---------
+[managed_identity][] | Managed Identity configuration for Azure API.    | no
+[oauth][]            | OAuth 2.0 configuration for Azure API.           | no
+[tls_config][]       | TLS configuration for requests to the Azure API. | no
 
-[oauth]: #oauth-block
-[managed_identity]: #managed_identity-block
-[tls_config]: #tls_config-block
+You must specify exactly one of the `oauth` or `managed_identity` blocks.
 
-### oauth block
-The `oauth` block configures OAuth authentication for the Azure API.
+[managed_identity]: #managed_identity
+[oauth]: #oauth
+[tls_config]: #tls_config
 
-Name            | Type     | Description          | Default | Required
-----------------|----------|----------------------|---------|---------
-`client_id`     | `string` | OAuth client ID.     |         | yes
-`client_secret` | `string` | OAuth client secret. |         | yes
-`tenant_id`     | `string` | OAuth tenant ID.     |         | yes
+### managed_identity
 
-### managed_identity block
 The `managed_identity` block configures Managed Identity authentication for the Azure API.
 
 Name        | Type     | Description                 | Default | Required
 ------------|----------|-----------------------------|---------|---------
 `client_id` | `string` | Managed Identity client ID. |         | yes
 
-### tls_config block
+### oauth
+
+The `oauth` block configures OAuth 2.0 authentication for the Azure API.
+
+Name            | Type     | Description              | Default | Required
+----------------|----------|--------------------------|---------|---------
+`client_id`     | `string` | OAuth 2.0 client ID.     |         | yes
+`client_secret` | `string` | OAuth 2.0 client secret. |         | yes
+`tenant_id`     | `string` | OAuth 2.0 tenant ID.     |         | yes
+
+### tls_config
+
+The `tls_config` block configures TLS settings for requests to the Azure API.
 
 {{< docs/shared lookup="reference/components/tls-config-block.md" source="alloy" version="<ALLOY_VERSION>" >}}
 
@@ -84,21 +88,22 @@ Name      | Type                | Description
 
 Each target includes the following labels:
 
-* `__meta_azure_subscription_id`: The Azure subscription ID.
-* `__meta_azure_tenant_id`: The Azure tenant ID.
-* `__meta_azure_machine_id`: The UUID of the Azure VM.
-* `__meta_azure_machine_resource_group`: The name of the resource group the VM is in.
-* `__meta_azure_machine_name`: The name of the VM.
 * `__meta_azure_machine_computer_name`: The host OS name of the VM.
-* `__meta_azure_machine_os_type`: The OS the VM is running (either `Linux` or `Windows`).
+* `__meta_azure_machine_id`: The UUID of the Azure VM.
 * `__meta_azure_machine_location`: The region the VM is in.
+* `__meta_azure_machine_name`: The name of the VM.
+* `__meta_azure_machine_os_type`: The OS the VM is running, either `Linux` or `Windows`.
 * `__meta_azure_machine_private_ip`: The private IP address of the VM.
 * `__meta_azure_machine_public_ip`: The public IP address of the VM.
-* `__meta_azure_machine_tag_*`: A tag on the VM. There will be one label per tag.
+* `__meta_azure_machine_resource_group`: The name of the resource group the VM is in.
 * `__meta_azure_machine_scale_set`: The name of the scale set the VM is in.
 * `__meta_azure_machine_size`: The size of the VM.
+* `__meta_azure_machine_tag_*`: A tag on the VM. There is one label per tag.
+* `__meta_azure_subscription_id`: The Azure subscription ID.
+* `__meta_azure_tenant_id`: The Azure tenant ID.
 
-Each discovered VM maps to a single target. The `__address__` label is set to the `private_ip:port` (`[private_ip]:port` if the private IP is an IPv6 address) of the VM.
+Each discovered VM maps to a single target.
+The `__address__` label is set to the `private_ip:port` of the VM if the private IP is an IPv4 address, or `[private_ip]:port` if the private IP of the VM is an IPv6 address.
 
 ## Component health
 
@@ -118,11 +123,11 @@ In those cases, exported fields retain their last healthy values.
 ```alloy
 discovery.azure "example" {
   port = 80
-  subscription_id = <AZURE_SUBSCRIPTION_ID>
+  subscription_id = "<AZURE_SUBSCRIPTION_ID>"
   oauth {
-      client_id = <AZURE_CLIENT_ID>
-      client_secret = <AZURE_CLIENT_SECRET>
-      tenant_id = <AZURE_TENANT_ID>
+      client_id = "<AZURE_CLIENT_ID>"
+      client_secret = "<AZURE_CLIENT_SECRET>"
+      tenant_id = "<AZURE_TENANT_ID>"
   }
 }
 
@@ -133,24 +138,25 @@ prometheus.scrape "demo" {
 
 prometheus.remote_write "demo" {
   endpoint {
-    url = <PROMETHEUS_REMOTE_WRITE_URL>
+    url = "<PROMETHEUS_REMOTE_WRITE_URL>"
 
     basic_auth {
-      username = <USERNAME>
-      password = <PASSWORD>
+      username = "<USERNAME>"
+      password = "<PASSWORD>"
     }
   }
 }
 ```
 
 Replace the following:
-  - _`<AZURE_SUBSCRIPTION_ID>`_: Your Azure subscription ID.
-  - _`<AZURE_CLIENT_ID>`_: Your Azure client ID.
-  - _`<AZURE_CLIENT_SECRET>`_: Your Azure client secret.
-  - _`<AZURE_TENANT_ID>`_: Your Azure tenant ID.
-  - _`<PROMETHEUS_REMOTE_WRITE_URL>`_: The URL of the Prometheus remote_write-compatible server to send metrics to.
-  - _`<USERNAME>`_: The username to use for authentication to the remote_write API.
-  - _`<PASSWORD>`_: The password to use for authentication to the remote_write API.
+
+* _`<AZURE_SUBSCRIPTION_ID>`_: Your Azure subscription ID.
+* _`<AZURE_CLIENT_ID>`_: Your Azure client ID.
+* _`<AZURE_CLIENT_SECRET>`_: Your Azure client secret.
+* _`<AZURE_TENANT_ID>`_: Your Azure tenant ID.
+* _`<PROMETHEUS_REMOTE_WRITE_URL>`_: The URL of the Prometheus remote_write-compatible server to send metrics to.
+* _`<USERNAME>`_: The username to use for authentication to the `remote_write` API.
+* _`<PASSWORD>`_: The password to use for authentication to the `remote_write` API.
 
 <!-- START GENERATED COMPATIBLE COMPONENTS -->
 
diff --git a/docs/sources/reference/components/discovery/discovery.consul.md b/docs/sources/reference/components/discovery/discovery.consul.md
index f2d09557ed..0a29a26fa8 100644
--- a/docs/sources/reference/components/discovery/discovery.consul.md
+++ b/docs/sources/reference/components/discovery/discovery.consul.md
@@ -8,53 +8,54 @@ title: discovery.consul
 
 # discovery.consul
 
-`discovery.consul` allows retrieving scrape targets from [Consul's Catalog API][].
+`discovery.consul` allows you to retrieve scrape targets from [Consul's Catalog API][].
 
 [Consul's Catalog API]: https://www.consul.io/use-cases/discover-services
 
 ## Usage
 
 ```alloy
-discovery.consul "LABEL" {
-  server = CONSUL_SERVER
+discovery.consul "<LABEL>" {
+  server = "<CONSUL_SERVER>"
 }
 ```
 
 ## Arguments
 
-The following arguments are supported:
+You can use the following arguments with `discovery.consul`:
 
 Name                     | Type                | Description                                                                                                     | Default          | Required
 -------------------------|---------------------|-----------------------------------------------------------------------------------------------------------------|------------------|---------
-`server`                 | `string`            | Host and port of the Consul API.                                                                                | `localhost:8500` | no
-`token`                  | `secret`            | Secret token used to access the Consul API.                                                                     |                  | no
-`datacenter`             | `string`            | Datacenter to query. If not provided, the default is used.                                                      |                  | no
-`namespace`              | `string`            | Namespace to use. Only supported in Consul Enterprise.                                                          |                  | no
-`partition`              | `string`            | Admin partition to use. Only supported in Consul Enterprise.                                                    |                  | no
-`tag_separator`          | `string`            | The string by which Consul tags are joined into the tag label.                                                  | `,`              | no
-`scheme`                 | `string`            | The scheme to use when talking to Consul.                                                                       | `http`           | no
-`username`               | `string`            | The username to use. Deprecated in favor of the `basic_auth` configuration.                                     |                  | no
-`password`               | `secret`            | The password to use. Deprecated in favor of the `basic_auth` configuration.                                     |                  | no
 `allow_stale`            | `bool`              | Allow stale Consul results. Reduces load on Consul. Refer to the [Consul documentation][] for more information. | `true`           | no
-`services`               | `list(string)`      | A list of services for which targets are retrieved. If omitted, all services are scraped.                       |                  | no
-`tags`                   | `list(string)`      | An optional list of tags used to filter nodes for a given service. Services must contain all tags in the list.  |                  | no
-`node_meta`              | `map(string)`       | Node metadata key/value pairs to filter nodes for a given service.                                              |                  | no
-`refresh_interval`       | `duration`          | Frequency to refresh list of containers.                                                                        | `"30s"`          | no
 `bearer_token_file`      | `string`            | File containing a bearer token to authenticate with.                                                            |                  | no
 `bearer_token`           | `secret`            | Bearer token to authenticate with.                                                                              |                  | no
+`datacenter`             | `string`            | Data center to query. If not provided, the default is used.                                                     |                  | no
 `enable_http2`           | `bool`              | Whether HTTP2 is supported for requests.                                                                        | `true`           | no
 `follow_redirects`       | `bool`              | Whether redirects returned by the server should be followed.                                                    | `true`           | no
-`proxy_url`              | `string`            | HTTP proxy to send requests through.                                                                            |                  | no
+`namespace`              | `string`            | Namespace to use. Only supported in Consul Enterprise.                                                          |                  | no
 `no_proxy`               | `string`            | Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying.                |                  | no
-`proxy_from_environment` | `bool`              | Use the proxy URL indicated by environment variables.                                                           | `false`          | no
+`node_meta`              | `map(string)`       | Node metadata key/value pairs to filter nodes for a given service.                                              |                  | no
+`partition`              | `string`            | Admin partition to use. Only supported in Consul Enterprise.                                                    |                  | no
+`password`               | `secret`            | The password to use. Deprecated in favor of the `basic_auth` configuration.                                     |                  | no
 `proxy_connect_header`   | `map(list(secret))` | Specifies headers to send to proxies during CONNECT requests.                                                   |                  | no
+`proxy_from_environment` | `bool`              | Use the proxy URL indicated by environment variables.                                                           | `false`          | no
+`proxy_url`              | `string`            | HTTP proxy to send requests through.                                                                            |                  | no
+`refresh_interval`       | `duration`          | Frequency to refresh list of containers.                                                                        | `"30s"`          | no
+`scheme`                 | `string`            | The scheme to use when talking to Consul.                                                                       | `http`           | no
+`server`                 | `string`            | Host and port of the Consul API.                                                                                | `localhost:8500` | no
+`services`               | `list(string)`      | A list of services for which targets are retrieved. If omitted, all services are scraped.                       |                  | no
+`tag_separator`          | `string`            | The string by which Consul tags are joined into the tag label.                                                  | `,`              | no
+`tags`                   | `list(string)`      | An optional list of tags used to filter nodes for a given service. Services must contain all tags in the list.  |                  | no
+`token`                  | `secret`            | Secret token used to access the Consul API.                                                                     |                  | no
+`username`               | `string`            | The username to use. Deprecated in favor of the `basic_auth` configuration.                                     |                  | no
 
  At most, one of the following can be provided:
- - [`bearer_token` argument](#arguments).
- - [`bearer_token_file` argument](#arguments).
- - [`basic_auth` block][basic_auth].
- - [`authorization` block][authorization].
- - [`oauth2` block][oauth2].
+
+* [`authorization`][authorization] block
+* [`basic_auth`][basic_auth] block
+* [`bearer_token_file`][arguments] argument
+* [`bearer_token`][arguments] argument
+* [`oauth2`][oauth2] block
 
 {{< docs/shared lookup="reference/components/http-client-proxy-config-description.md" source="alloy" version="<ALLOY_VERSION>" >}}
 
@@ -63,38 +64,45 @@ Name                     | Type                | Description
 
 ## Blocks
 
-The following blocks are supported inside the definition of
-`discovery.consul`:
+You can use the following blocks with `discovery.consul`:
 
-Hierarchy           | Block             | Description                                                | Required
---------------------|-------------------|------------------------------------------------------------|---------
-basic_auth          | [basic_auth][]    | Configure `basic_auth` for authenticating to the endpoint. | no
-authorization       | [authorization][] | Configure generic authorization to the endpoint.           | no
-oauth2              | [oauth2][]        | Configure OAuth2 for authenticating to the endpoint.       | no
-oauth2 > tls_config | [tls_config][]    | Configure TLS settings for connecting to the endpoint.     | no
-tls_config          | [tls_config][]    | Configure TLS settings for connecting to the endpoint.     | no
+Block                   | Description                                                | Required
+------------------------|------------------------------------------------------------|---------
+[authorization][]       | Configure generic authorization to the endpoint.           | no
+[basic_auth][]          | Configure `basic_auth` for authenticating to the endpoint. | no
+[oauth2][]              | Configure OAuth 2.0 for authenticating to the endpoint.    | no
+oauth2 > [tls_config][] | Configure TLS settings for connecting to the endpoint.     | no
+[tls_config][]          | Configure TLS settings for connecting to the endpoint.     | no
 
-The `>` symbol indicates deeper levels of nesting.
+The > symbol indicates deeper levels of nesting.
 For example, `oauth2 > tls_config` refers to a `tls_config` block defined inside an `oauth2` block.
 
-[basic_auth]: #basic_auth-block
-[authorization]: #authorization-block
-[oauth2]: #oauth2-block
-[tls_config]: #tls_config-block
+[authorization]: #authorization
+[basic_auth]: #basic_auth
+[oauth2]: #oauth2
+[tls_config]: #tls_config
 
-### basic_auth block
+### authorization
 
-{{< docs/shared lookup="reference/components/basic-auth-block.md" source="alloy" version="<ALLOY_VERSION>" >}}
-
-### authorization block
+The `authorization` block configures generic authorization to the endpoint.
 
 {{< docs/shared lookup="reference/components/authorization-block.md" source="alloy" version="<ALLOY_VERSION>" >}}
 
-### oauth2 block
+### basic_auth
+
+The `basic_auth` block configures basic authentication to the endpoint.
+
+{{< docs/shared lookup="reference/components/basic-auth-block.md" source="alloy" version="<ALLOY_VERSION>" >}}
+
+### oauth2
+
+The `oauth` block configures OAuth 2.0 authentication to the endpoint.
 
 {{< docs/shared lookup="reference/components/oauth2-block.md" source="alloy" version="<ALLOY_VERSION>" >}}
 
-### tls_config block
+### tls_config
+
+The `tls_config` block configures TLS settings for connecting to the endpoint.
 
 {{< docs/shared lookup="reference/components/tls-config-block.md" source="alloy" version="<ALLOY_VERSION>" >}}
 
@@ -109,9 +117,9 @@ Name      | Type                | Description
 Each target includes the following labels:
 
 * `__meta_consul_address`: The address of the target.
-* `__meta_consul_partition`: The admin partition name where the service is registered.
 * `__meta_consul_metadata_<key>`: Each node metadata key value of the target.
 * `__meta_consul_node`: The node name defined for the target.
+* `__meta_consul_partition`: The administrator partition name where the service is registered.
 * `__meta_consul_service_address`: The service address of the target.
 * `__meta_consul_service_id`: The service ID of the target.
 * `__meta_consul_service_metadata_<key>`: Each service metadata key value of the target.
@@ -153,19 +161,21 @@ prometheus.scrape "demo" {
 
 prometheus.remote_write "demo" {
   endpoint {
-    url = <PROMETHEUS_REMOTE_WRITE_URL>
+    url = "<PROMETHEUS_REMOTE_WRITE_URL>"
 
     basic_auth {
-      username = <USERNAME>
-      password = <PASSWORD>
+      username = "<USERNAME>"
+      password = "<PASSWORD>"
     }
   }
 }
 ```
+
 Replace the following:
-  - _`<PROMETHEUS_REMOTE_WRITE_URL>`_: The URL of the Prometheus remote_write-compatible server to send metrics to.
-  - _`<USERNAME>`_: The username to use for authentication to the `remote_write` API.
-  - _`<PASSWORD>`_: The password to use for authentication to the `remote_write` API.
+
+* _`<PROMETHEUS_REMOTE_WRITE_URL>`_: The URL of the Prometheus remote_write-compatible server to send metrics to.
+* _`<USERNAME>`_: The username to use for authentication to the `remote_write` API.
+* _`<PASSWORD>`_: The password to use for authentication to the `remote_write` API.
 
 <!-- START GENERATED COMPATIBLE COMPONENTS -->
 
diff --git a/docs/sources/reference/components/discovery/discovery.consulagent.md b/docs/sources/reference/components/discovery/discovery.consulagent.md
index 17eb8acb6a..3f7dd6d125 100644
--- a/docs/sources/reference/components/discovery/discovery.consulagent.md
+++ b/docs/sources/reference/components/discovery/discovery.consulagent.md
@@ -9,7 +9,7 @@ title: discovery.consulagent
 # discovery.consulagent
 
 `discovery.consulagent` allows you to retrieve scrape targets from [Consul's Agent API][].
-Only the services registered with the local agent running on the same host will be watched.
+Only the services registered with the local agent running on the same host are watched.
 This is suitable for very large Consul clusters for which using the Catalog API would be too slow or resource intensive.
 
 [Consul's Agent API]: https://developer.hashicorp.com/consul/api-docs/agent
@@ -17,40 +17,41 @@ This is suitable for very large Consul clusters for which using the Catalog API
 ## Usage
 
 ```alloy
-discovery.consulagent "LABEL" {
-  server = CONSUL_SERVER
+discovery.consulagent "<LABEL>" {
+  server = "<CONSUL_SERVER>"
 }
 ```
 
 ## Arguments
 
-The following arguments are supported:
-
-| Name               | Type           | Description                                                                                                                          | Default          | Required |
-|--------------------|----------------|--------------------------------------------------------------------------------------------------------------------------------------|------------------|----------|
-| `server`           | `string`       | Host and port of the Consul Agent API.                                                                                               | `localhost:8500` | no       |
-| `token`            | `secret`       | Secret token used to access the Consul Agent API.                                                                                    |                  | no       |
-| `datacenter`       | `string`       | Datacenter in which the Consul Agent is configured to run. If not provided, the datacenter is retrieved from the local Consul Agent. |                  | no       |
-| `tag_separator`    | `string`       | The string by which Consul tags are joined into the tag label.                                                                       | `,`              | no       |
-| `scheme`           | `string`       | The scheme to use when talking to the Consul Agent.                                                                                  | `http`           | no       |
-| `username`         | `string`       | The username to use.                                                                                                                 |                  | no       |
-| `password`         | `secret`       | The password to use.                                                                                                                 |                  | no       |
-| `services`         | `list(string)` | A list of services for which targets are retrieved. If omitted, all services are scraped.                                            |                  | no       |
-| `tags`             | `list(string)` | An optional list of tags used to filter nodes for a given service. Services must contain all tags in the list.                       |                  | no       |
-| `refresh_interval` | `duration`     | Frequency to refresh list of containers.                                                                                             | `"30s"`          | no       |
+You can use the following arguments with `discovery.consulagent`:
+
+Name               | Type           | Description                                                                                                                            | Default          | Required
+-------------------|----------------|----------------------------------------------------------------------------------------------------------------------------------------|------------------|---------
+`datacenter`       | `string`       | Data center in which the Consul Agent is configured to run. If not provided, the data center is retrieved from the local Consul Agent. |                  | no
+`password`         | `secret`       | The password to use.                                                                                                                   |                  | no
+`refresh_interval` | `duration`     | Frequency to refresh list of containers.                                                                                               | `"30s"`          | no
+`scheme`           | `string`       | The scheme to use when talking to the Consul Agent.                                                                                    | `http`           | no
+`server`           | `string`       | Host and port of the Consul Agent API.                                                                                                 | `localhost:8500` | no
+`services`         | `list(string)` | A list of services for which targets are retrieved. If omitted, all services are scraped.                                              |                  | no
+`tag_separator`    | `string`       | The string by which Consul tags are joined into the tag label.                                                                         | `,`              | no
+`tags`             | `list(string)` | An optional list of tags used to filter nodes for a given service. Services must contain all tags in the list.                         |                  | no
+`token`            | `secret`       | Secret token used to access the Consul Agent API.                                                                                      |                  | no
+`username`         | `string`       | The username to use.                                                                                                                   |                  | no
 
 ## Blocks
 
-The following blocks are supported inside the definition of
-`discovery.consulagent`:
+You can use the following blocks with `discovery.consulagent`:
 
-| Hierarchy  | Block          | Description                                            | Required |
-| ---------- | -------------- | ------------------------------------------------------ | -------- |
-| tls_config | [tls_config][] | Configure TLS settings for connecting to the endpoint. | no       |
+Block          | Description                                            | Required
+---------------|--------------------------------------------------------|---------
+[tls_config][] | Configure TLS settings for connecting to the endpoint. | no
 
-[tls_config]: #tls_config-block
+[tls_config]: #tls_config
 
-### tls_config block
+### tls_config
+
+The `tls_config` block configures TLS settings for connecting to the endpoint.
 
 {{< docs/shared lookup="reference/components/tls-config-block.md" source="alloy" version="<ALLOY_VERSION>" >}}
 
@@ -58,24 +59,24 @@ The following blocks are supported inside the definition of
 
 The following fields are exported and can be referenced by other components:
 
-| Name      | Type                | Description                                              |
-| --------- | ------------------- | -------------------------------------------------------- |
-| `targets` | `list(map(string))` | The set of targets discovered from the Consul Agent API. |
+Name      | Type                | Description
+----------|---------------------|---------------------------------------------------------
+`targets` | `list(map(string))` | The set of targets discovered from the Consul Agent API.
 
 Each target includes the following labels:
 
-- `__meta_consulagent_address`: The address of the target.
-- `__meta_consulagent_dc`: The datacenter name for the target.
-- `__meta_consulagent_health`: The health status of the service.
-- `__meta_consulagent_metadata_<key>`: Each node metadata key value of the target.
-- `__meta_consulagent_node`: The node name defined for the target.
-- `__meta_consulagent_service`: The name of the service the target belongs to.
-- `__meta_consulagent_service_address`: The service address of the target.
-- `__meta_consulagent_service_id`: The service ID of the target.
-- `__meta_consulagent_service_metadata_<key>`: Each service metadata key value of the target.
-- `__meta_consulagent_service_port`: The service port of the target.
-- `__meta_consulagent_tagged_address_<key>`: Each node tagged address key value of the target.
-- `__meta_consulagent_tags`: The list of tags of the target joined by the tag separator.
+* `__meta_consulagent_address`: The address of the target.
+* `__meta_consulagent_dc`: The data center name for the target.
+* `__meta_consulagent_health`: The health status of the service.
+* `__meta_consulagent_metadata_<key>`: Each node metadata key value of the target.
+* `__meta_consulagent_node`: The node name defined for the target.
+* `__meta_consulagent_service_address`: The service address of the target.
+* `__meta_consulagent_service_id`: The service ID of the target.
+* `__meta_consulagent_service_metadata_<key>`: Each service metadata key value of the target.
+* `__meta_consulagent_service_port`: The service port of the target.
+* `__meta_consulagent_service`: The name of the service the target belongs to.
+* `__meta_consulagent_tagged_address_<key>`: Each node tagged address key value of the target.
+* `__meta_consulagent_tags`: The list of tags of the target joined by the tag separator.
 
 ## Component health
 
@@ -88,8 +89,8 @@ In those cases, exported fields retain their last healthy values.
 
 ## Debug metrics
 
-- `discovery_consulagent_rpc_failures_total` (Counter): The number of Consul Agent RPC call failures.
-- `discovery_consulagent_rpc_duration_seconds` (SummaryVec): The duration of a Consul Agent RPC call in seconds.
+* `discovery_consulagent_rpc_duration_seconds` (SummaryVec): The duration of a Consul Agent RPC call in seconds.
+* `discovery_consulagent_rpc_failures_total` (Counter): The number of Consul Agent RPC call failures.
 
 ## Example
 
@@ -112,11 +113,11 @@ prometheus.scrape "demo" {
 
 prometheus.remote_write "demo" {
   endpoint {
-    url = <PROMETHEUS_REMOTE_WRITE_URL>
+    url = "<PROMETHEUS_REMOTE_WRITE_URL>"
 
     basic_auth {
-      username = <USERNAME>
-      password = <PASSWORD>
+      username = "<USERNAME>"
+      password = "<PASSWORD>"
     }
   }
 }
@@ -124,9 +125,9 @@ prometheus.remote_write "demo" {
 
 Replace the following:
 
-- _`<PROMETHEUS_REMOTE_WRITE_URL>`_: The URL of the Prometheus remote_write-compatible server to send metrics to.
-- _`<USERNAME>`_: The username to use for authentication to the remote_write API.
-- _`<PASSWORD>`_: The password to use for authentication to the remote_write API.
+* _`<PROMETHEUS_REMOTE_WRITE_URL>`_: The URL of the Prometheus remote_write-compatible server to send metrics to.
+* _`<USERNAME>`_: The username to use for authentication to the `remote_write` API.
+* _`<PASSWORD>`_: The password to use for authentication to the `remote_write` API.
 
 <!-- START GENERATED COMPATIBLE COMPONENTS -->
 
diff --git a/docs/sources/reference/components/discovery/discovery.digitalocean.md b/docs/sources/reference/components/discovery/discovery.digitalocean.md
index f0f4bcbcc0..60ad5f7593 100644
--- a/docs/sources/reference/components/discovery/discovery.digitalocean.md
+++ b/docs/sources/reference/components/discovery/discovery.digitalocean.md
@@ -15,41 +15,41 @@ title: discovery.digitalocean
 ## Usage
 
 ```alloy
-discovery.digitalocean "LABEL" {
+discovery.digitalocean "<LABEL>" {
     // Use one of:
-    // bearer_token      = BEARER_TOKEN
-    // bearer_token_file = PATH_TO_BEARER_TOKEN_FILE
+    // bearer_token      = "<BEARER_TOKEN>"
+    // bearer_token_file = "<PATH_TO_BEARER_TOKEN_FILE>"
 }
 ```
 
 ## Arguments
 
-The following arguments are supported:
+You can use the following arguments with `discovery.digitalocean`:
 
 Name                     | Type                | Description                                                                                      | Default | Required
 -------------------------|---------------------|--------------------------------------------------------------------------------------------------|---------|---------
-`port`                   | `number`            | Port to be appended to the `__address__` label for each Droplet.                                 | `80`    | no
-`refresh_interval`       | `duration`          | Frequency to refresh list of Droplets.                                                           | `"1m"`  | no
-`bearer_token`           | `secret`            | Bearer token to authenticate with.                                                               |         | no
 `bearer_token_file`      | `string`            | File containing a bearer token to authenticate with.                                             |         | no
-`proxy_url`              | `string`            | HTTP proxy to send requests through.                                                             |         | no
+`bearer_token`           | `secret`            | Bearer token to authenticate with.                                                               |         | no
+`enable_http2`           | `bool`              | Whether HTTP2 is supported for requests.                                                         | `true`  | no
+`follow_redirects`       | `bool`              | Whether redirects returned by the server should be followed.                                     | `true`  | no
 `no_proxy`               | `string`            | Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying. |         | no
-`proxy_from_environment` | `bool`              | Use the proxy URL indicated by environment variables.                                            | `false` | no
+`port`                   | `number`            | Port to be appended to the `__address__` label for each Droplet.                                 | `80`    | no
 `proxy_connect_header`   | `map(list(secret))` | Specifies headers to send to proxies during CONNECT requests.                                    |         | no
-`follow_redirects`       | `bool`              | Whether redirects returned by the server should be followed.                                     | `true`  | no
-`enable_http2`           | `bool`              | Whether HTTP2 is supported for requests.                                                         | `true`  | no
+`proxy_from_environment` | `bool`              | Use the proxy URL indicated by environment variables.                                            | `false` | no
+`proxy_url`              | `string`            | HTTP proxy to send requests through.                                                             |         | no
+`refresh_interval`       | `duration`          | Frequency to refresh list of Droplets.                                                           | `"1m"`  | no
 
 The DigitalOcean API uses bearer tokens for authentication, see more about it in the [DigitalOcean API documentation](https://docs.digitalocean.com/reference/api/api-reference/#section/Authentication).
 
-Exactly one of the [`bearer_token`](#arguments) and [`bearer_token_file`](#arguments) arguments must be specified to authenticate against DigitalOcean.
+Exactly one of the [`bearer_token`][arguments] and [`bearer_token_file`][arguments] arguments must be specified to authenticate against DigitalOcean.
 
 [arguments]: #arguments
 
 {{< docs/shared lookup="reference/components/http-client-proxy-config-description.md" source="alloy" version="<ALLOY_VERSION>" >}}
 
 ## Blocks
-The `discovery.digitalocean` component doesn't support any blocks, and is configured fully through arguments.
 
+The `discovery.digitalocean` component doesn't support any blocks. You can configure this component with arguments.
 
 ## Exported fields
 
@@ -63,15 +63,15 @@ Each target includes the following labels:
 
 * `__meta_digitalocean_droplet_id`: ID of the Droplet.
 * `__meta_digitalocean_droplet_name`: Name of the Droplet.
-* `__meta_digitalocean_image`: The image slug (unique text identifier of the image) used to create the Droplet.
+* `__meta_digitalocean_features`: Optional properties configured for the Droplet, such as IPV6 networking, private networking, or backups.
 * `__meta_digitalocean_image_name`: Name of the image used to create the Droplet.
+* `__meta_digitalocean_image`: The image slug (unique text identifier of the image) used to create the Droplet.
 * `__meta_digitalocean_private_ipv4`: The private IPv4 address of the Droplet.
 * `__meta_digitalocean_public_ipv4`: The public IPv4 address of the Droplet.
 * `__meta_digitalocean_public_ipv6`: The public IPv6 address of the Droplet.
 * `__meta_digitalocean_region`: The region the Droplet is running in.
 * `__meta_digitalocean_size`: The size of the Droplet.
 * `__meta_digitalocean_status`: The current status of the Droplet.
-* `__meta_digitalocean_features`: Optional properties configured for the Droplet, such as IPV6 networking, private networking, or backups.
 * `__meta_digitalocean_tags`: The tags assigned to the Droplet.
 * `__meta_digitalocean_vpc`: The ID of the VPC where the Droplet is located.
 
@@ -79,9 +79,8 @@ Each discovered Droplet maps to one target.
 
 ## Component health
 
-`discovery.digitalocean` is only reported as unhealthy when given an invalid
-configuration. In those cases, exported fields retain their last healthy
-values.
+`discovery.digitalocean` is only reported as unhealthy when given an invalid configuration.
+In those cases, exported fields retain their last healthy values.
 
 ## Debug information
 
@@ -94,6 +93,7 @@ values.
 ## Example
 
 This would result in targets with `__address__` labels like: `192.0.2.1:8080`:
+
 ```alloy
 discovery.digitalocean "example" {
   port             = 8080
@@ -108,19 +108,21 @@ prometheus.scrape "demo" {
 
 prometheus.remote_write "demo" {
   endpoint {
-    url = <PROMETHEUS_REMOTE_WRITE_URL>
+    url = "<PROMETHEUS_REMOTE_WRITE_URL>"
 
     basic_auth {
-      username = <USERNAME>
-      password = <PASSWORD>
+      username = "<USERNAME>"
+      password = "<PASSWORD>"
     }
   }
 }
 ```
+
 Replace the following:
-  - _`<PROMETHEUS_REMOTE_WRITE_URL>`_: The URL of the Prometheus remote_write-compatible server to send metrics to.
-  - _`<USERNAME>`_: The username to use for authentication to the remote_write API.
-  - _`<PASSWORD>`_: The password to use for authentication to the remote_write API.
+
+* _`<PROMETHEUS_REMOTE_WRITE_URL>`_: The URL of the Prometheus remote_write-compatible server to send metrics to.
+* _`<USERNAME>`_: The username to use for authentication to the `remote_write` API.
+* _`<PASSWORD>`_: The password to use for authentication to the `remote_write` API.
 
 <!-- START GENERATED COMPATIBLE COMPONENTS -->
 
diff --git a/docs/sources/reference/components/discovery/discovery.dns.md b/docs/sources/reference/components/discovery/discovery.dns.md
index 7c441b8bf1..2e66991f02 100644
--- a/docs/sources/reference/components/discovery/discovery.dns.md
+++ b/docs/sources/reference/components/discovery/discovery.dns.md
@@ -13,14 +13,14 @@ title: discovery.dns
 ## Usage
 
 ```alloy
-discovery.dns "LABEL" {
-  names = [NAME_1, NAME_2, ...]
+discovery.dns "<LABEL>" {
+  names = ["<NAME_1>", "<NAME_2>", ...]
 }
 ```
 
 ## Arguments
 
-The following arguments are supported:
+You can use the following arguments with `discovery.dns`:
 
 Name               | Type           | Description                                                          | Default | Required
 -------------------|----------------|----------------------------------------------------------------------|---------|---------
@@ -29,21 +29,25 @@ Name               | Type           | Description
 `refresh_interval` | `duration`     | How often to query DNS for updates.                                  | `"30s"` | no
 `type`             | `string`       | Type of DNS record to query. Must be one of SRV, A, AAAA, MX, or NS. | `"SRV"` | no
 
+## Blocks
+
+The `discovery.dns` component doesn't support any blocks. You can configure this component with arguments.
+
 ## Exported fields
 
 The following field is exported and can be referenced by other components:
 
-Name | Type | Description
----- | ---- | -----------
+Name      | Type                | Description
+----------|---------------------|---------------------------------------------------
 `targets` | `list(map(string))` | The set of targets discovered from the docker API.
 
 Each target includes the following labels:
 
-* `__meta_dns_name`: Name of the record that produced the discovered target.
-* `__meta_dns_srv_record_target`: Target field of the SRV record.
-* `__meta_dns_srv_record_port`: Port field of the SRV record.
 * `__meta_dns_mx_record_target`: Target field of the MX record.
+* `__meta_dns_name`: Name of the record that produced the discovered target.
 * `__meta_dns_ns_record_target`: Target field of the NS record.
+* `__meta_dns_srv_record_port`: Port field of the SRV record.
+* `__meta_dns_srv_record_target`: Target field of the SRV record.
 
 ## Component health
 
@@ -52,11 +56,11 @@ In those cases, exported fields retain their last healthy values.
 
 ## Debug information
 
-`discovery.dns` does not expose any component-specific debug information.
+`discovery.dns` doesn't expose any component-specific debug information.
 
 ## Debug metrics
 
-`discovery.dns` does not expose any component-specific debug metrics.
+`discovery.dns` doesn't expose any component-specific debug metrics.
 
 ## Example
 
@@ -76,19 +80,21 @@ prometheus.scrape "demo" {
 
 prometheus.remote_write "demo" {
   endpoint {
-    url = PROMETHEUS_REMOTE_WRITE_URL
+    url = "<PROMETHEUS_REMOTE_WRITE_URL>"
 
     basic_auth {
-      username = USERNAME
-      password = PASSWORD
+      username = "<USERNAME>"
+      password = "<PASSWORD>"
     }
   }
 }
 ```
+
 Replace the following:
-  - `PROMETHEUS_REMOTE_WRITE_URL`: The URL of the Prometheus remote_write-compatible server to send metrics to.
-  - `USERNAME`: The username to use for authentication to the remote_write API.
-  - `PASSWORD`: The password to use for authentication to the remote_write API.
+
+* _`<PROMETHEUS_REMOTE_WRITE_URL>`_: The URL of the Prometheus remote_write-compatible server to send metrics to.
+* _`<USERNAME>`_: The username to use for authentication to the `remote_write` API.
+* _`<PASSWORD>`_: The password to use for authentication to the `remote_write` API.
 
 <!-- START GENERATED COMPATIBLE COMPONENTS -->
 
diff --git a/docs/sources/reference/components/discovery/discovery.docker.md b/docs/sources/reference/components/discovery/discovery.docker.md
index e1a689515f..316b2ee163 100644
--- a/docs/sources/reference/components/discovery/discovery.docker.md
+++ b/docs/sources/reference/components/discovery/discovery.docker.md
@@ -15,36 +15,37 @@ title: discovery.docker
 ## Usage
 
 ```alloy
-discovery.docker "LABEL" {
-  host = DOCKER_ENGINE_HOST
+discovery.docker "<LABEL>" {
+  host = "<DOCKER_ENGINE_HOST>"
 }
 ```
 
 ## Arguments
 
-The following arguments are supported:
+You can use the following arguments with `discovery.docker`:
 
 Name                     | Type                | Description                                                                                      | Default       | Required
 -------------------------|---------------------|--------------------------------------------------------------------------------------------------|---------------|---------
 `host`                   | `string`            | Address of the Docker Daemon to connect to.                                                      |               | yes
-`port`                   | `number`            | Port to use for collecting metrics when containers don't have any port mappings.                 | `80`          | no
-`host_networking_host`   | `string`            | Host to use if the container is in host networking mode.                                         | `"localhost"` | no
-`refresh_interval`       | `duration`          | Frequency to refresh list of containers.                                                         | `"1m"`        | no
 `bearer_token_file`      | `string`            | File containing a bearer token to authenticate with.                                             |               | no
 `bearer_token`           | `secret`            | Bearer token to authenticate with.                                                               |               | no
 `enable_http2`           | `bool`              | Whether HTTP2 is supported for requests.                                                         | `true`        | no
 `follow_redirects`       | `bool`              | Whether redirects returned by the server should be followed.                                     | `true`        | no
-`proxy_url`              | `string`            | HTTP proxy to send requests through.                                                             |               | no
+`host_networking_host`   | `string`            | Host to use if the container is in host networking mode.                                         | `"localhost"` | no
 `no_proxy`               | `string`            | Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying. |               | no
-`proxy_from_environment` | `bool`              | Use the proxy URL indicated by environment variables.                                            | `false`       | no
+`port`                   | `number`            | Port to use for collecting metrics when containers don't have any port mappings.                 | `80`          | no
 `proxy_connect_header`   | `map(list(secret))` | Specifies headers to send to proxies during CONNECT requests.                                    |               | no
+`proxy_from_environment` | `bool`              | Use the proxy URL indicated by environment variables.                                            | `false`       | no
+`proxy_url`              | `string`            | HTTP proxy to send requests through.                                                             |               | no
+`refresh_interval`       | `duration`          | Frequency to refresh list of containers.                                                         | `"1m"`        | no
 
  At most, one of the following can be provided:
- - [`bearer_token` argument](#arguments).
- - [`bearer_token_file` argument](#arguments).
- - [`basic_auth` block][basic_auth].
- - [`authorization` block][authorization].
- - [`oauth2` block][oauth2].
+
+* [`authorization`][authorization] block
+* [`basic_auth`][basic_auth] block
+* [`bearer_token_file`][arguments] argument
+* [`bearer_token`][arguments] argument
+* [`oauth2`][oauth2] block
 
 [arguments]: #arguments
 
@@ -52,31 +53,42 @@ Name                     | Type                | Description
 
 ## Blocks
 
-The following blocks are supported inside the definition of
-`discovery.docker`:
+You can use the following blocks with `discovery.docker`:
 
-Hierarchy           | Block             | Description                                              | Required
---------------------|-------------------|----------------------------------------------------------|---------
-filter              | [filter][]        | Filters discoverable resources.                          | no
-basic_auth          | [basic_auth][]    | Configure basic_auth for authenticating to the endpoint. | no
-authorization       | [authorization][] | Configure generic authorization to the endpoint.         | no
-oauth2              | [oauth2][]        | Configure OAuth2 for authenticating to the endpoint.     | no
-oauth2 > tls_config | [tls_config][]    | Configure TLS settings for connecting to the endpoint.   | no
-tls_config          | [tls_config][]    | Configure TLS settings for connecting to the endpoint.   | no
+Block                   | Description                                                | Required
+------------------------|------------------------------------------------------------|---------
+[authorization][]       | Configure generic authorization to the endpoint.           | no
+[basic_auth][]          | Configure `basic_auth` for authenticating to the endpoint. | no
+[filter][]              | Filters discoverable resources.                            | no
+[oauth2][]              | Configure OAuth 2.0 for authenticating to the endpoint.    | no
+oauth2 > [tls_config][] | Configure TLS settings for connecting to the endpoint.     | no
+[tls_config][]          | Configure TLS settings for connecting to the endpoint.     | no
 
 The `>` symbol indicates deeper levels of nesting.
 For example, `oauth2 > tls_config` refers to a `tls_config` block defined inside an `oauth2` block.
 
-[filter]: #filter-block
-[basic_auth]: #basic_auth-block
-[authorization]: #authorization-block
-[oauth2]: #oauth2-block
-[tls_config]: #tls_config-block
+[filter]: #filter
+[basic_auth]: #basic_auth
+[authorization]: #authorization
+[oauth2]: #oauth2
+[tls_config]: #tls_config
+
+### authorization
+
+The `authorization` block configures generic authorization to the endpoint.
+
+{{< docs/shared lookup="reference/components/authorization-block.md" source="alloy" version="<ALLOY_VERSION>" >}}
+
+### basic_auth
+
+The `basic_auth` block configures basic authentication to the endpoint.
 
-### filter block
+{{< docs/shared lookup="reference/components/basic-auth-block.md" source="alloy" version="<ALLOY_VERSION>" >}}
 
-The `filter` block configures a filter to pass to the Docker Engine to limit the amount of containers returned.
-The `filter` block can be specified multiple times to provide more than one filter.
+### filter
+
+The `filter` block configures a filter to pass to the Docker Engine to limit the number of containers returned.
+You can specify the `filter` block multiple times to provide more than one filter.
 
 Name     | Type           | Description                   | Default | Required
 ---------|----------------|-------------------------------|---------|---------
@@ -87,19 +99,15 @@ Refer to [List containers][List containers] from the Docker Engine API documenta
 
 [List containers]: https://docs.docker.com/engine/api/v1.41/#tag/Container/operation/ContainerList
 
-### basic_auth block
+### oauth2
 
-{{< docs/shared lookup="reference/components/basic-auth-block.md" source="alloy" version="<ALLOY_VERSION>" >}}
-
-### authorization block
-
-{{< docs/shared lookup="reference/components/authorization-block.md" source="alloy" version="<ALLOY_VERSION>" >}}
-
-### oauth2 block
+The `oauth` block configures OAuth 2.0 authentication to the endpoint.
 
 {{< docs/shared lookup="reference/components/oauth2-block.md" source="alloy" version="<ALLOY_VERSION>" >}}
 
-### tls_config block
+### tls_config
+
+The `tls_config` block configures TLS settings for connecting to the endpoint.
 
 {{< docs/shared lookup="reference/components/tls-config-block.md" source="alloy" version="<ALLOY_VERSION>" >}}
 
@@ -114,19 +122,19 @@ Name      | Type                | Description
 Each target includes the following labels:
 
 * `__meta_docker_container_id`: ID of the container.
+* `__meta_docker_container_label_<labelname>`: Each label from the container.
 * `__meta_docker_container_name`: Name of the container.
 * `__meta_docker_container_network_mode`: Network mode of the container.
-* `__meta_docker_container_label_<labelname>`: Each label from the container.
 * `__meta_docker_network_id`: ID of the Docker network the container is in.
-* `__meta_docker_network_name`: Name of the Docker network the container is in.
 * `__meta_docker_network_ingress`: Set to `true` if the Docker network is an ingress network.
 * `__meta_docker_network_internal`: Set to `true` if the Docker network is an internal network.
+* `__meta_docker_network_ip`: The IP of the container in the network.
 * `__meta_docker_network_label_<labelname>`: Each label from the network the container is in.
+* `__meta_docker_network_name`: Name of the Docker network the container is in.
 * `__meta_docker_network_scope`: The scope of the network the container is in.
-* `__meta_docker_network_ip`: The IP of the container in the network.
 * `__meta_docker_port_private`: The private port on the container.
-* `__meta_docker_port_public`: The publicly exposed port from the container, if a port mapping exists.
 * `__meta_docker_port_public_ip`: The public IP of the container, if a port mapping exists.
+* `__meta_docker_port_public`: The publicly exposed port from the container, if a port mapping exists.
 
 Each discovered container maps to one target per unique combination of networks and port mappings used by the container.
 
@@ -137,11 +145,11 @@ In those cases, exported fields retain their last healthy values.
 
 ## Debug information
 
-`discovery.docker` does not expose any component-specific debug information.
+`discovery.docker` doesn't expose any component-specific debug information.
 
 ## Debug metrics
 
-`discovery.docker` does not expose any component-specific debug metrics.
+`discovery.docker` doesn't expose any component-specific debug metrics.
 
 ## Examples
 
@@ -161,24 +169,30 @@ prometheus.scrape "demo" {
 
 prometheus.remote_write "demo" {
   endpoint {
-    url = PROMETHEUS_REMOTE_WRITE_URL
+    url = "<PROMETHEUS_REMOTE_WRITE_URL>"
 
     basic_auth {
-      username = USERNAME
-      password = PASSWORD
+      username = "<USERNAME>"
+      password = "<PASSWORD>"
     }
   }
 }
 ```
+
 Replace the following:
-  - `PROMETHEUS_REMOTE_WRITE_URL`: The URL of the Prometheus remote_write-compatible server to send metrics to.
-  - `USERNAME`: The username to use for authentication to the remote_write API.
-  - `PASSWORD`: The password to use for authentication to the remote_write API.
+
+* _`<PROMETHEUS_REMOTE_WRITE_URL>`_: The URL of the Prometheus remote_write-compatible server to send metrics to.
+* _`<USERNAME>`_: The username to use for authentication to the `remote_write` API.
+* _`<PASSWORD>`_: The password to use for authentication to the `remote_write` API.
 
 ### Windows hosts
 
 This example discovers Docker containers when the host machine is Windows:
 
+{{< admonition type="note" >}}
+This example requires the "Expose daemon on tcp://localhost:2375 without TLS" setting to be enabled in the Docker Engine settings.
+{{< /admonition >}}
+
 ```alloy
 discovery.docker "containers" {
   host = "tcp://localhost:2375"
@@ -191,22 +205,21 @@ prometheus.scrape "demo" {
 
 prometheus.remote_write "demo" {
   endpoint {
-    url = PROMETHEUS_REMOTE_WRITE_URL
+    url = "<PROMETHEUS_REMOTE_WRITE_URL>"
 
     basic_auth {
-      username = USERNAME
-      password = PASSWORD
+      username = "<USERNAME>"
+      password = "<PASSWORD>"
     }
   }
 }
 ```
+
 Replace the following:
-  - `PROMETHEUS_REMOTE_WRITE_URL`: The URL of the Prometheus remote_write-compatible server to send metrics to.
-  - `USERNAME`: The username to use for authentication to the remote_write API.
-  - `PASSWORD`: The password to use for authentication to the remote_write API.
 
-> **NOTE**: This example requires the "Expose daemon on tcp://localhost:2375
-> without TLS" setting to be enabled in the Docker Engine settings.
+* _`<PROMETHEUS_REMOTE_WRITE_URL>`_: The URL of the Prometheus remote_write-compatible server to send metrics to.
+* _`<USERNAME>`_: The username to use for authentication to the `remote_write` API.
+* _`<PASSWORD>`_: The password to use for authentication to the `remote_write` API.
 
 <!-- START GENERATED COMPATIBLE COMPONENTS -->
 
diff --git a/docs/sources/reference/components/discovery/discovery.dockerswarm.md b/docs/sources/reference/components/discovery/discovery.dockerswarm.md
index ce3a636105..88462d5fb8 100644
--- a/docs/sources/reference/components/discovery/discovery.dockerswarm.md
+++ b/docs/sources/reference/components/discovery/discovery.dockerswarm.md
@@ -13,37 +13,38 @@ title: discovery.dockerswarm
 ## Usage
 
 ```alloy
-discovery.dockerswarm "LABEL" {
-  host = "DOCKER_DAEMON_HOST"
-  role = "SWARM_ROLE"
+discovery.dockerswarm "<LABEL>" {
+  host = "<DOCKER_DAEMON_HOST>"
+  role = "<SWARM_ROLE>"
 }
 ```
 
 ## Arguments
 
-The following arguments are supported:
+You can use the following arguments with `discovery.dockerswarm`:
 
 Name                     | Type                | Description                                                                                                                   | Default | Required
 -------------------------|---------------------|-------------------------------------------------------------------------------------------------------------------------------|---------|---------
 `host`                   | `string`            | Address of the Docker daemon.                                                                                                 |         | yes
 `role`                   | `string`            | Role of the targets to retrieve. Must be `services`, `tasks`, or `nodes`.                                                     |         | yes
-`port`                   | `number`            | The port to scrape metrics from, when `role` is nodes, and for discovered tasks and services that don't have published ports. | `80`    | no
-`refresh_interval`       | `duration`          | Interval at which to refresh the list of targets.                                                                             | `"60s"` | no
 `bearer_token_file`      | `string`            | File containing a bearer token to authenticate with.                                                                          |         | no
 `bearer_token`           | `secret`            | Bearer token to authenticate with.                                                                                            |         | no
 `enable_http2`           | `bool`              | Whether HTTP2 is supported for requests.                                                                                      | `true`  | no
 `follow_redirects`       | `bool`              | Whether redirects returned by the server should be followed.                                                                  | `true`  | no
-`proxy_url`              | `string`            | HTTP proxy to send requests through.                                                                                          |         | no
 `no_proxy`               | `string`            | Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying.                              |         | no
-`proxy_from_environment` | `bool`              | Use the proxy URL indicated by environment variables.                                                                         | `false` | no
+`port`                   | `number`            | The port to scrape metrics from, when `role` is nodes, and for discovered tasks and services that don't have published ports. | `80`    | no
 `proxy_connect_header`   | `map(list(secret))` | Specifies headers to send to proxies during CONNECT requests.                                                                 |         | no
+`proxy_from_environment` | `bool`              | Use the proxy URL indicated by environment variables.                                                                         | `false` | no
+`proxy_url`              | `string`            | HTTP proxy to send requests through.                                                                                          |         | no
+`refresh_interval`       | `duration`          | Interval at which to refresh the list of targets.                                                                             | `"60s"` | no
 
  At most, one of the following can be provided:
- - [`bearer_token` argument](#arguments).
- - [`bearer_token_file` argument](#arguments).
- - [`basic_auth` block][basic_auth].
- - [`authorization` block][authorization].
- - [`oauth2` block][oauth2].
+
+* [`authorization`][authorization] block
+* [`basic_auth`][basic_auth] block
+* [`bearer_token_file`][arguments] argument
+* [`bearer_token`][arguments] argument
+* [`oauth2`][oauth2] block
 
 {{< docs/shared lookup="reference/components/http-client-proxy-config-description.md" source="alloy" version="<ALLOY_VERSION>" >}}
 
@@ -51,58 +52,64 @@ Name                     | Type                | Description
 
 ## Blocks
 
-The following blocks are supported inside the definition of
-`discovery.dockerswarm`:
+You can use the following blocks with `discovery.dockerswarm`:
 
-| Hierarchy           | Block             | Description                                                                        | Required |
-| ------------------- | ----------------- | ---------------------------------------------------------------------------------- | -------- |
-| filter              | [filter][]        | Optional filter to limit the discovery process to a subset of available resources. | no       |
-| basic_auth          | [basic_auth][]    | Configure basic_auth for authenticating to the endpoint.                           | no       |
-| authorization       | [authorization][] | Configure generic authorization to the endpoint.                                   | no       |
-| oauth2              | [oauth2][]        | Configure OAuth2 for authenticating to the endpoint.                               | no       |
-| oauth2 > tls_config | [tls_config][]    | Configure TLS settings for connecting to the endpoint.                             | no       |
-| tls_config          | [tls_config][]    | Configure TLS settings for connecting to the endpoint.                             | no       |
+Block                   | Description                                                                        | Required
+------------------------|------------------------------------------------------------------------------------|---------
+[authorization][]       | Configure generic authorization to the endpoint.                                   | no
+[basic_auth][]          | Configure `basic_auth` for authenticating to the endpoint.                         | no
+[filter][]              | Optional filter to limit the discovery process to a subset of available resources. | no
+[oauth2][]              | Configure OAuth2 for authenticating to the endpoint.                               | no
+oauth2 > [tls_config][] | Configure TLS settings for connecting to the endpoint.                             | no
+[tls_config][]          | Configure TLS settings for connecting to the endpoint.                             | no
 
-The `>` symbol indicates deeper levels of nesting. For example,
-`oauth2 > tls_config` refers to a `tls_config` block defined inside
-an `oauth2` block.
+The `>` symbol indicates deeper levels of nesting.
+For example, `oauth2 > tls_config` refers to a `tls_config` block defined inside an `oauth2` block.
 
-[filter]: #filter-block
-[basic_auth]: #basic_auth-block
-[authorization]: #authorization-block
-[oauth2]: #oauth2-block
-[tls_config]: #tls_config-block
+[filter]: #filter
+[basic_auth]: #basic_auth
+[authorization]: #authorization
+[oauth2]: #oauth2
+[tls_config]: #tls_config
 
-### filter block
+### authorization
 
-Filters can be used to limit the discovery process to a subset of available resources.
-It is possible to define multiple `filter` blocks within the `discovery.dockerswarm` block.
-The list of available filters depends on the `role`:
+The `authorization` block configures generic authorization to the endpoint.
 
-- [services filters](https://docs.docker.com/engine/api/v1.40/#operation/ServiceList)
-- [tasks filters](https://docs.docker.com/engine/api/v1.40/#operation/TaskList)
-- [nodes filters](https://docs.docker.com/engine/api/v1.40/#operation/NodeList)
-
-The following arguments can be used to configure a filter.
+{{< docs/shared lookup="reference/components/authorization-block.md" source="alloy" version="<ALLOY_VERSION>" >}}
 
-| Name     | Type           | Description                                | Default | Required |
-| -------- | -------------- | ------------------------------------------ | ------- | -------- |
-| `name`   | `string`       | Name of the filter.                        |         | yes      |
-| `values` | `list(string)` | List of values associated with the filter. |         | yes      |
+### basic_auth
 
-### basic_auth block
+The `basic_auth` block configures basic authentication to the endpoint.
 
 {{< docs/shared lookup="reference/components/basic-auth-block.md" source="alloy" version="<ALLOY_VERSION>" >}}
 
-### authorization block
+### filter
 
-{{< docs/shared lookup="reference/components/authorization-block.md" source="alloy" version="<ALLOY_VERSION>" >}}
+The `filter` block limits the discovery process to a subset of available resources.
+You can define multiple `filter` blocks within the `discovery.dockerswarm` block.
+The list of available filters depends on the `role`:
+
+* [nodes filters](https://docs.docker.com/engine/api/v1.40/#operation/NodeList)
+* [services filters](https://docs.docker.com/engine/api/v1.40/#operation/ServiceList)
+* [tasks filters](https://docs.docker.com/engine/api/v1.40/#operation/TaskList)
 
-### oauth2 block
+You can use the following arguments to configure a filter.
+
+Name     | Type           | Description                                | Default | Required
+---------|----------------|--------------------------------------------|---------|---------
+`name`   | `string`       | Name of the filter.                        |         | yes
+`values` | `list(string)` | List of values associated with the filter. |         | yes
+
+### oauth2
+
+The `oauth` block configures OAuth 2.0 authentication to the endpoint.
 
 {{< docs/shared lookup="reference/components/oauth2-block.md" source="alloy" version="<ALLOY_VERSION>" >}}
 
-### tls_config block
+### tls_config
+
+The `tls_config` block configures TLS settings for connecting to the endpoint.
 
 {{< docs/shared lookup="reference/components/tls-config-block.md" source="alloy" version="<ALLOY_VERSION>" >}}
 
@@ -110,9 +117,9 @@ The following arguments can be used to configure a filter.
 
 The following fields are exported and can be referenced by other components:
 
-| Name      | Type                | Description                               |
-| --------- | ------------------- | ----------------------------------------- |
-| `targets` | `list(map(string))` | The set of targets discovered from Swarm. |
+Name      | Type                | Description
+----------|---------------------|------------------------------------------
+`targets` | `list(map(string))` | The set of targets discovered from Swarm.
 
 ## Roles
 
@@ -126,21 +133,21 @@ If a service has no published ports, a target per service is created using the `
 
 Available meta labels:
 
-- `__meta_dockerswarm_service_id`: the ID of the service.
-- `__meta_dockerswarm_service_name`: the name of the service.
-- `__meta_dockerswarm_service_mode`: the mode of the service.
-- `__meta_dockerswarm_service_endpoint_port_name`: the name of the endpoint port, if available.
-- `__meta_dockerswarm_service_endpoint_port_publish_mode`: the publish mode of the endpoint port.
-- `__meta_dockerswarm_service_label_<labelname>`: each label of the service.
-- `__meta_dockerswarm_service_task_container_hostname`: the container hostname of the target, if available.
-- `__meta_dockerswarm_service_task_container_image`: the container image of the target.
-- `__meta_dockerswarm_service_updating_status`: the status of the service, if available.
-- `__meta_dockerswarm_network_id`: the ID of the network.
-- `__meta_dockerswarm_network_name`: the name of the network.
-- `__meta_dockerswarm_network_ingress`: whether the network is ingress.
-- `__meta_dockerswarm_network_internal`: whether the network is internal.
-- `__meta_dockerswarm_network_label_<labelname>`: each label of the network.
-- `__meta_dockerswarm_network_scope`: the scope of the network.
+* `__meta_dockerswarm_network_id`: The ID of the network.
+* `__meta_dockerswarm_network_ingress`: Whether the network is ingress.
+* `__meta_dockerswarm_network_internal`: Whether the network is internal.
+* `__meta_dockerswarm_network_label_<labelname>`: Each label of the network.
+* `__meta_dockerswarm_network_name`: The name of the network.
+* `__meta_dockerswarm_network_scope`: The scope of the network.
+* `__meta_dockerswarm_service_endpoint_port_name`: The name of the endpoint port, if available.
+* `__meta_dockerswarm_service_endpoint_port_publish_mode`: The publish mode of the endpoint port.
+* `__meta_dockerswarm_service_id`: The ID of the service.
+* `__meta_dockerswarm_service_label_<labelname>`: Each label of the service.
+* `__meta_dockerswarm_service_mode`: The mode of the service.
+* `__meta_dockerswarm_service_name`: The name of the service.
+* `__meta_dockerswarm_service_task_container_hostname`: The container hostname of the target, if available.
+* `__meta_dockerswarm_service_task_container_image`: The container image of the target.
+* `__meta_dockerswarm_service_updating_status`: The status of the service, if available.
 
 ### tasks
 
@@ -150,35 +157,35 @@ If a task has no published ports, a target per task is created using the `port`
 
 Available meta labels:
 
-- `__meta_dockerswarm_container_label_<labelname>`: each label of the container.
-- `__meta_dockerswarm_task_id`: the ID of the task.
-- `__meta_dockerswarm_task_container_id`: the container ID of the task.
-- `__meta_dockerswarm_task_desired_state`: the desired state of the task.
-- `__meta_dockerswarm_task_slot`: the slot of the task.
-- `__meta_dockerswarm_task_state`: the state of the task.
-- `__meta_dockerswarm_task_port_publish_mode`: the publish mode of the task port.
-- `__meta_dockerswarm_service_id`: the ID of the service.
-- `__meta_dockerswarm_service_name`: the name of the service.
-- `__meta_dockerswarm_service_mode`: the mode of the service.
-- `__meta_dockerswarm_service_label_<labelname>`: each label of the service.
-- `__meta_dockerswarm_network_id`: the ID of the network.
-- `__meta_dockerswarm_network_name`: the name of the network.
-- `__meta_dockerswarm_network_ingress`: whether the network is ingress.
-- `__meta_dockerswarm_network_internal`: whether the network is internal.
-- `__meta_dockerswarm_network_label_<labelname>`: each label of the network.
-- `__meta_dockerswarm_network_label`: each label of the network.
-- `__meta_dockerswarm_network_scope`: the scope of the network.
-- `__meta_dockerswarm_node_id`: the ID of the node.
-- `__meta_dockerswarm_node_hostname`: the hostname of the node.
-- `__meta_dockerswarm_node_address`: the address of the node.
-- `__meta_dockerswarm_node_availability`: the availability of the node.
-- `__meta_dockerswarm_node_label_<labelname>`: each label of the node.
-- `__meta_dockerswarm_node_platform_architecture`: the architecture of the node.
-- `__meta_dockerswarm_node_platform_os`: the operating system of the node.
-- `__meta_dockerswarm_node_role`: the role of the node.
-- `__meta_dockerswarm_node_status`: the status of the node.
-
-The `__meta_dockerswarm_network_*` meta labels are not populated for ports which are published with mode=host.
+* `__meta_dockerswarm_container_label_<labelname>`: Each label of the container.
+* `__meta_dockerswarm_network_id`: The ID of the network.
+* `__meta_dockerswarm_network_ingress`: Whether the network is ingress.
+* `__meta_dockerswarm_network_internal`: Whether the network is internal.
+* `__meta_dockerswarm_network_label_<labelname>`: Each label of the network.
+* `__meta_dockerswarm_network_label`: Each label of the network.
+* `__meta_dockerswarm_network_name`: The name of the network.
+* `__meta_dockerswarm_network_scope`: The scope of the network.
+* `__meta_dockerswarm_node_address`: The address of the node.
+* `__meta_dockerswarm_node_availability`: The availability of the node.
+* `__meta_dockerswarm_node_hostname`: The hostname of the node.
+* `__meta_dockerswarm_node_id`: The ID of the node.
+* `__meta_dockerswarm_node_label_<labelname>`: Each label of the node.
+* `__meta_dockerswarm_node_platform_architecture`: The architecture of the node.
+* `__meta_dockerswarm_node_platform_os`: The operating system of the node.
+* `__meta_dockerswarm_node_role`: The role of the node.
+* `__meta_dockerswarm_node_status`: The status of the node.
+* `__meta_dockerswarm_service_id`: The ID of the service.
+* `__meta_dockerswarm_service_label_<labelname>`: Each label of the service.
+* `__meta_dockerswarm_service_mode`: The mode of the service.
+* `__meta_dockerswarm_service_name`: The name of the service.
+* `__meta_dockerswarm_task_container_id`: The container ID of the task.
+* `__meta_dockerswarm_task_desired_state`: The desired state of the task.
+* `__meta_dockerswarm_task_id`: The ID of the task.
+* `__meta_dockerswarm_task_port_publish_mode`: The publish mode of the task port.
+* `__meta_dockerswarm_task_slot`: The slot of the task.
+* `__meta_dockerswarm_task_state`: The state of the task.
+
+The `__meta_dockerswarm_network_*` meta labels aren't populated for ports which are published with mode=host.
 
 ### nodes
 
@@ -186,19 +193,19 @@ The `nodes` role is used to discover [Swarm nodes](https://docs.docker.com/engin
 
 Available meta labels:
 
-- `__meta_dockerswarm_node_address`: the address of the node.
-- `__meta_dockerswarm_node_availability`: the availability of the node.
-- `__meta_dockerswarm_node_engine_version`: the version of the node engine.
-- `__meta_dockerswarm_node_hostname`: the hostname of the node.
-- `__meta_dockerswarm_node_id`: the ID of the node.
-- `__meta_dockerswarm_node_label_<labelname>`: each label of the node.
-- `__meta_dockerswarm_node_manager_address`: the address of the manager component of the node.
-- `__meta_dockerswarm_node_manager_leader`: the leadership status of the manager component of the node (true or false).
-- `__meta_dockerswarm_node_manager_reachability`: the reachability of the manager component of the node.
-- `__meta_dockerswarm_node_platform_architecture`: the architecture of the node.
-- `__meta_dockerswarm_node_platform_os`: the operating system of the node.
-- `__meta_dockerswarm_node_role`: the role of the node.
-- `__meta_dockerswarm_node_status`: the status of the node.
+* `__meta_dockerswarm_node_address`: The address of the node.
+* `__meta_dockerswarm_node_availability`: The availability of the node.
+* `__meta_dockerswarm_node_engine_version`: The version of the node engine.
+* `__meta_dockerswarm_node_hostname`: The hostname of the node.
+* `__meta_dockerswarm_node_id`: The ID of the node.
+* `__meta_dockerswarm_node_label_<labelname>`: Each label of the node.
+* `__meta_dockerswarm_node_manager_address`: The address of the manager component of the node.
+* `__meta_dockerswarm_node_manager_leader`: The leadership status of the manager component of the node (true or false).
+* `__meta_dockerswarm_node_manager_reachability`: The reachability of the manager component of the node.
+* `__meta_dockerswarm_node_platform_architecture`: The architecture of the node.
+* `__meta_dockerswarm_node_platform_os`: The operating system of the node.
+* `__meta_dockerswarm_node_role`: The role of the node.
+* `__meta_dockerswarm_node_status`: The status of the node.
 
 ## Component health
 
@@ -207,11 +214,11 @@ In those cases, exported fields retain their last healthy values.
 
 ## Debug information
 
-`discovery.dockerswarm` does not expose any component-specific debug information.
+`discovery.dockerswarm` doesn't expose any component-specific debug information.
 
 ## Debug metrics
 
-`discovery.dockerswarm` does not expose any component-specific debug metrics.
+`discovery.dockerswarm` doesn't expose any component-specific debug metrics.
 
 ## Example
 
@@ -240,11 +247,11 @@ prometheus.scrape "demo" {
 
 prometheus.remote_write "demo" {
   endpoint {
-    url = PROMETHEUS_REMOTE_WRITE_URL
+    url = "<PROMETHEUS_REMOTE_WRITE_URL>"
 
     basic_auth {
-      username = USERNAME
-      password = PASSWORD
+      username = "<USERNAME>"
+      password = "<PASSWORD>"
     }
   }
 }
@@ -252,9 +259,9 @@ prometheus.remote_write "demo" {
 
 Replace the following:
 
-- `PROMETHEUS_REMOTE_WRITE_URL`: The URL of the Prometheus remote_write-compatible server to send metrics to.
-- `USERNAME`: The username to use for authentication to the remote_write API.
-- `PASSWORD`: The password to use for authentication to the remote_write API.
+* _`<PROMETHEUS_REMOTE_WRITE_URL>`_: The URL of the Prometheus remote_write-compatible server to send metrics to.
+* _`<USERNAME>`_: The username to use for authentication to the `remote_write` API.
+* _`<PASSWORD>`_: The password to use for authentication to the `remote_write` API.
 
 <!-- START GENERATED COMPATIBLE COMPONENTS -->