General cleanup of relref links (#6509)

* Convert relrefs to doc reference * Update more relrefs to doc references * Fix table format and remove unused relref * Update import.http and remotecfg * Update links in argument topic * Convert to doc reference in declare * Fix table formatting * Clean up table * Clean up tables, convert a ref to doc reference * Add doc references and clean up tables * General syntax tidy
grafana · Feb 23, 2024 · b8c4c99 · b8c4c99
1 parent e41c1f4
commit b8c4c99
Show file tree

Hide file tree

Showing 10 changed files with 162 additions and 150 deletions.
diff --git a/docs/sources/flow/_index.md b/docs/sources/flow/_index.md
@@ -70,7 +70,7 @@ prometheus.remote_write "default" {
 
 ## {{% param "PRODUCT_NAME" %}} configuration generator
 
-The {{< param "PRODUCT_NAME" >}} [configuration generator](https://grafana.github.io/agent-configurator/) will help you get a head start on creating flow code.
+The {{< param "PRODUCT_NAME" >}} [configuration generator](https://grafana.github.io/agent-configurator/) helps you get a head start on creating flow code.
 
 {{< admonition type="note" >}}
 This feature is experimental, and it doesn't support all River components.
@@ -80,14 +80,19 @@ This feature is experimental, and it doesn't support all River components.
 
 * [Install][] {{< param "PRODUCT_NAME" >}}.
 * Learn about the core [Concepts][] of {{< param "PRODUCT_NAME" >}}.
-* Follow our [Tutorials][] for hands-on learning of {{< param "PRODUCT_NAME" >}}.
-* Consult our [Tasks][] instructions to accomplish common objectives with {{< param "PRODUCT_NAME" >}}.
-* Check out our [Reference][] documentation to find specific information you
-  might be looking for.
-
-[Install]: {{< relref "./get-started/install/" >}}
-[Concepts]: {{< relref "./concepts/" >}}
-[Tasks]: {{< relref "./tasks/" >}}
-[Tutorials]: {{< relref "./tutorials/ ">}}
-[Reference]: {{< relref "./reference" >}}
-
+* Follow the [Tutorials][] for hands-on learning of {{< param "PRODUCT_NAME" >}}.
+* Consult the [Tasks][] instructions to accomplish common objectives with {{< param "PRODUCT_NAME" >}}.
+* Check out the [Reference][] documentation to find specific information you might be looking for.
+
+{{% docs/reference %}}
+[Install]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/get-started/install/"
+[Install]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/get-started/install/"
+[Concepts]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/concepts/"
+[Concepts]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/concepts/"
+[Tasks]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/tasks/"
+[Tasks]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/tasks/"
+[Tutorials]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/tutorials/"
+[Tutorials]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/tutorials/
+[Reference]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/"
+[Reference]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/reference/
+{{% /docs/reference %}}
diff --git a/docs/sources/flow/reference/config-blocks/argument.md b/docs/sources/flow/reference/config-blocks/argument.md
@@ -18,14 +18,12 @@ title: argument block
 The `argument` block may only be specified inside the definition of [a `declare` block][declare].
 
 {{< admonition type="note" >}}
-In [classic modules][], the `argument` block is valid as a top-level block in a classic module. Classic modules are deprecated and scheduled to be removed in the release after v0.40.
+In [classic modules][], the `argument` block is valid as a top-level block in a classic module.
+Classic modules are deprecated and scheduled to be removed in the release after v0.40.
 
-[classic modules]: {{< relref "../../concepts/modules.md#classic-modules-deprecated" >}}
+[classic modules]: https://grafana.com/docs/agent/<AGENT_VERSION>/flow/concepts/modules/#classic-modules-deprecated
 {{< /admonition >}}
 
-[custom component]: {{< relref "../../concepts/custom_components.md" >}}
-[declare]: {{< relref "./declare.md" >}}
-
 ## Example
 
 ```river
@@ -34,9 +32,10 @@ argument "ARGUMENT_NAME" {}
 
 ## Arguments
 
-> **NOTE**: For clarity, "argument" in this section refers to arguments which
-> can be given to the argument block. "Module argument" refers to the argument
-> being defined for a module, determined by the label of the argument block.
+{{< admonition type="note" >}}
+For clarity, "argument" in this section refers to arguments which can be given to the argument block.
+"Module argument" refers to the argument being defined for a module, determined by the label of the argument block.
+{{< /admonition >}}
 
 The following arguments are supported:
 
@@ -46,21 +45,20 @@ Name       | Type     | Description                          | Default | Require
 `default`  | `any`    | Default value for the argument.      | `null`  | no
 `optional` | `bool`   | Whether the argument may be omitted. | `false` | no
 
-By default, all module arguments are required. The `optional` argument can be
-used to mark the module argument as optional. When `optional` is `true`, the
-initial value for the module argument is specified by `default`.
+By default, all module arguments are required.
+The `optional` argument can be used to mark the module argument as optional.
+When `optional` is `true`, the initial value for the module argument is specified by `default`.
 
 ## Exported fields
 
 The following fields are exported and can be referenced by other components:
 
-Name | Type | Description
----- | ---- | -----------
+Name    | Type  | Description
+--------|-------|-----------------------------------
 `value` | `any` | The current value of the argument.
 
 If you use a custom component, you are responsible for determining the values for arguments.
-Other expressions within a custom component may use `argument.ARGUMENT_NAME.value` to retrieve the
-value you provide.
+Other expressions within a custom component may use `argument.ARGUMENT_NAME.value` to retrieve the value you provide.
 
 ## Example
 
@@ -82,3 +80,10 @@ declare "self_collect" {
   }
 }
 ```
+
+{{% docs/reference %}}
+[custom component]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/concepts/custom_components"
+[custom component]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/concepts/custom_components"
+[declare]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/config-blocks/declare"
+[declare]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/reference/config-blocks/declare"
+{{% /docs/reference %}}
diff --git a/docs/sources/flow/reference/config-blocks/declare.md b/docs/sources/flow/reference/config-blocks/declare.md
@@ -15,8 +15,6 @@ title: declare block
 `declare` is an optional configuration block used to define a new [custom component][].
 `declare` blocks must be given a label that determines the name of the custom component.
 
-[custom component]: {{< relref "../../concepts/custom_components.md" >}}
-
 ## Example
 
 ```river
@@ -27,28 +25,22 @@ declare "COMPONENT_NAME" {
 
 ## Arguments
 
-The `declare` block has no predefined schema for its arguments; the body of the
-`declare` block is used as the component definition. The body may contain:
+The `declare` block has no predefined schema for its arguments.
+The body of the `declare` block is used as the component definition.
+The body can contain the following:
 
 * [argument][] blocks
 * [export][] blocks
 * [declare][] blocks
 * [import][] blocks
 * Component definitions (either built-in or custom components)
 
-The `declare` block may not contain any configuration blocks that are not
-listed above.
-
-[argument]: {{< relref "./argument.md" >}}
-[export]: {{< relref "./export.md" >}}
-[declare]: {{< relref "./declare.md" >}}
-[import]: {{< relref "../../concepts/modules.md#importing-modules" >}}
+The `declare` block may not contain any configuration blocks that aren't listed above.
 
 ## Exported fields
 
-The `declare` block has no predefined schema for its exports; the fields
-exported by the `declare` block are determined by the [export blocks][export]
-found in its definition.
+The `declare` block has no predefined schema for its exports.
+The fields exported by the `declare` block are determined by the [export blocks][export] found in its definition.
 
 ## Example
 
@@ -80,3 +72,14 @@ prometheus.remote_write "example" {
   }
 }
 ```
+
+{{% docs/reference %}}
+[argument]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/config-blocks/argument"
+[argument]:"/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/reference/config-blocks/argument"
+[export]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/config-blocks/export"
+[export]:"/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/reference/config-blocks/export"
+[declare]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/config-blocks/declare"
+[declare]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/reference/config-blocks/declare"
+[import]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/concepts/modules#importing-modules"
+[import]:"/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/concepts/modules#importing-modules"
+{{% /docs/reference %}}
diff --git a/docs/sources/flow/reference/config-blocks/export.md b/docs/sources/flow/reference/config-blocks/export.md
@@ -20,12 +20,9 @@ The `export` block may only be specified inside the definition of [a `declare` b
 {{< admonition type="note" >}}
 In [classic modules][], the `export` block is valid as a top-level block in a classic module. Classic modules are deprecated and scheduled to be removed in the release after v0.40.
 
-[classic modules]: {{< relref "../../concepts/modules.md#classic-modules-deprecated" >}}
+[classic modules]: https://grafana.com/docs/agent/<AGENT_VERSION>/flow/concepts/modules/#classic-modules-deprecated
 {{< /admonition >}}
 
-[custom component]: {{< relref "../../concepts/custom_components.md" >}}
-[declare]: {{< relref "./declare.md" >}}
-
 ## Example
 
 ```river
@@ -42,7 +39,7 @@ Name    | Type  | Description      | Default | Required
 --------|-------|------------------|---------|---------
 `value` | `any` | Value to export. |         | yes
 
-The `value` argument determines what the value of the export will be.
+The `value` argument determines what the value of the export is.
 To expose an exported field of another component, set `value` to an expression that references that exported value.
 
 ## Exported fields
@@ -71,3 +68,10 @@ declare "pods_and_nodes" {
   }
 }
 ```
+
+{{% docs/reference %}}
+[custom component]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/concepts/custom_components"
+[custom component]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/concepts/custom_components"
+[declare]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/config-blocks/declare"
+[declare]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/reference/config-blocks/declare"
+{{% /docs/reference %}}
diff --git a/docs/sources/flow/reference/config-blocks/http.md b/docs/sources/flow/reference/config-blocks/http.md
@@ -57,35 +57,33 @@ Similarly, if you remove the `tls` block and reload the configuration when {{< p
 To ensure all connections use TLS, configure the `tls` block before you start {{< param "PRODUCT_NAME" >}}.
 {{< /admonition >}}
 
-Name | Type | Description | Default | Required
----- | ---- | ----------- | ------- | --------
-`cert_pem` | `string` | PEM data of the server TLS certificate. | `""` | conditionally
-`cert_file` | `string` | Path to the server TLS certificate on disk. | `""` | conditionally
-`key_pem` | `string` | PEM data of the server TLS key. | `""` | conditionally
-`key_file` | `string` | Path to the server TLS key on disk. | `""` | conditionally
-`client_ca_pem` | `string` | PEM data of the client CA to validate requests against. | `""` | no
-`client_ca_file` | `string` | Path to the client CA file on disk to validate requests against. | `""` | no
-`client_auth_type` | `string` | Client authentication to use. | `"NoClientCert"` | no
-`cipher_suites` | `list(string)` | Set of cipher suites to use. | `[]` | no
-`curve_preferences` | `list(string)` | Set of elliptic curves to use in a handshake. | `[]` | no
-`min_version` | `string` | Oldest TLS version to accept from clients. | `""` | no
-`max_version` | `string` | Newest TLS version to accept from clients. | `""` | no
+Name                | Type           | Description                                                      | Default          | Required
+--------------------|----------------|------------------------------------------------------------------|------------------|--------------
+`cert_pem`          | `string`       | PEM data of the server TLS certificate.                          | `""`             | conditionally
+`cert_file`         | `string`       | Path to the server TLS certificate on disk.                      | `""`             | conditionally
+`key_pem`           | `string`       | PEM data of the server TLS key.                                  | `""`             | conditionally
+`key_file`          | `string`       | Path to the server TLS key on disk.                              | `""`             | conditionally
+`client_ca_pem`     | `string`       | PEM data of the client CA to validate requests against.          | `""`             | no
+`client_ca_file`    | `string`       | Path to the client CA file on disk to validate requests against. | `""`             | no
+`client_auth_type`  | `string`       | Client authentication to use.                                    | `"NoClientCert"` | no
+`cipher_suites`     | `list(string)` | Set of cipher suites to use.                                     | `[]`             | no
+`curve_preferences` | `list(string)` | Set of elliptic curves to use in a handshake.                    | `[]`             | no
+`min_version`       | `string`       | Oldest TLS version to accept from clients.                       | `""`             | no
+`max_version`       | `string`       | Newest TLS version to accept from clients.                       | `""`             | no
 
 When the `tls` block is specified, arguments for the TLS certificate (using
 `cert_pem` or `cert_file`) and for the TLS key (using `key_pem` or `key_file`)
 are required.
 
-The following pairs of arguments are mutually exclusive, and only one may be
-configured at a time:
+The following pairs of arguments are mutually exclusive, and only one may be configured at a time:
 
 * `cert_pem` and `cert_file`
 * `key_pem` and `key_file`
 * `client_ca_pem` and `client_ca_file`
 
 The `client_auth_type` argument determines whether to validate client certificates.
-The default value, `NoClientCert`, indicates that the client certificate is not
-validated. The `client_ca_pem` and `client_ca_file` arguments may only
-be configured when `client_auth_type` is not `NoClientCert`.
+The default value, `NoClientCert`, indicates that the client certificate is not validated.
+The `client_ca_pem` and `client_ca_file` arguments may only be configured when `client_auth_type` is not `NoClientCert`.
 
 The following values are accepted for `client_auth_type`:
 
@@ -95,13 +93,12 @@ The following values are accepted for `client_auth_type`:
 * `VerifyClientCertIfGiven`: requests clients to send an optional certificate. If a certificate is sent, it must be valid.
 * `RequireAndVerifyClientCert`: requires clients to send a valid certificate.
 
-The `client_ca_pem` or `client_ca_file` arguments may be used to perform client
-certificate validation. These arguments may only be provided when `client_auth_type`
-is not set to `NoClientCert`.
+The `client_ca_pem` or `client_ca_file` arguments may be used to perform client certificate validation.
+These arguments may only be provided when `client_auth_type` is not set to `NoClientCert`.
 
-The `cipher_suites` argument determines what cipher suites to use. If not
-provided, a default list is used. The set of cipher suites specified may be
-from the following:
+The `cipher_suites` argument determines what cipher suites to use.
+If you don't provide cipher suite, a default list is used.
+The set of cipher suites specified may be from the following:
 
 | Cipher                                          | Allowed in `boringcrypto` builds |
 | ----------------------------------------------- | -------------------------------- |
@@ -134,9 +131,8 @@ is used. The set of elliptic curves specified may be from the following:
 | `CurveP521` | yes                              |
 | `X25519`    | no                               |
 
-The `min_version` and `max_version` arguments determine the oldest and newest
-TLS version that is acceptable from clients. If not provided, a default value
-is used.
+The `min_version` and `max_version` arguments determine the oldest and newest TLS version that's acceptable from clients.
+If you don't provide the min and max TLS version, a default value is used.
 
 The following versions are recognized:
 
@@ -148,9 +144,8 @@ The following versions are recognized:
 
 ### windows certificate filter block
 
-The `windows_certificate_filter` block is used to configure retrieving certificates from the built-in Windows
-certificate store. When you use the `windows_certificate_filter` block
-the following TLS settings are overridden and will cause an error if defined.
+The `windows_certificate_filter` block is used to configure retrieving certificates from the built-in Windows certificate store.
+When you use the `windows_certificate_filter` block the following TLS settings are overridden and cause an error if defined.
 
 * `cert_pem`
 * `cert_file`
@@ -162,15 +157,15 @@ the following TLS settings are overridden and will cause an error if defined.
 {{< admonition type="warning" >}}
 This feature is only available on Windows.
 
-TLS min and max may not be compatible with the certificate stored in the Windows certificate store. The `windows_certificate_filter`
-will serve the found certificate even if it is not compatible with the specified TLS version.
+TLS min and max may not be compatible with the certificate stored in the Windows certificate store.
+The `windows_certificate_filter` serves the certificate even if it isn't compatible with the specified TLS version.
 {{< /admonition >}}
 
 
 ### server block
 
-The `server` block is used to find the certificate to check the signer. If multiple certificates are found the
-`windows_certificate_filter` will choose the certificate with the expiration farthest in the future.
+The `server` block is used to find the certificate to check the signer.
+If multiple certificates are found, the `windows_certificate_filter` chooses the certificate with the expiration farthest in the future.
 
 Name                  | Type           | Description                                                                                          | Default | Required
 ----------------------|----------------|------------------------------------------------------------------------------------------------------|---------|---------

diff --git a/docs/sources/flow/reference/config-blocks/import.file.md b/docs/sources/flow/reference/config-blocks/import.file.md
@@ -18,8 +18,6 @@ title: import.file
 The `import.file` block imports custom components from a file and exposes them to the importer.
 `import.file` blocks must be given a label that determines the namespace where custom components are exposed.
 
-[module]: {{< relref "../../concepts/modules.md" >}}
-
 ## Usage
 
 ```river
@@ -32,11 +30,11 @@ import.file "NAMESPACE" {
 
 The following arguments are supported:
 
-Name | Type | Description | Default | Required
----- | ---- | ----------- | ------- | --------
-`filename`       | `string`   | Path of the file on disk to watch. | | yes
+Name             | Type       | Description                                         | Default      | Required
+-----------------|------------|-----------------------------------------------------|--------------|---------
+`filename`       | `string`   | Path of the file on disk to watch.                  |              | yes
 `detector`       | `string`   | Which file change detector to use (fsnotify, poll). | `"fsnotify"` | no
-`poll_frequency` | `duration` | How often to poll for file changes. | `"1m"` | no
+`poll_frequency` | `duration` | How often to poll for file changes.                 | `"1m"`       | no
 
 {{< docs/shared lookup="flow/reference/components/local-file-arguments-text.md" source="agent" version="<AGENT_VERSION>" >}}
 
@@ -69,3 +67,8 @@ math.add "default" {
 }
 ```
 {{< /collapse >}}
+
+{{% docs/reference %}}
+[module]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/concepts/modules"
+[module]:"/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/concepts/modules"
+{{% /docs/reference %}}