Refactor task based docs

.cursor/rules/alloy-docs.mdc

@@ -0,0 +1,117 @@
+---
+description: Guidelines for writing Alloy collect/task documentation pages in docs/sources/
+globs: docs/sources/monitor-applications/**/*.md,docs/sources/monitor-infrastructure/**/*.md
+alwaysApply: false
+---
+
+# Alloy task-based documentation pages
+
+## General style guidelines
+
+- End sentences that introduce code blocks with a **period**, not a colon.
+- For full style guidance, refer to `.docs/agent/style.md`, `.docs/agent/role.md`, `.docs/agent/grafana.md`, and `docs/developer/writing-docs.md`.
+- Before writing any config, read the reference doc in `docs/sources/reference/components/` for every component used. Check for deprecated arguments, blocks, and components, and always follow the best practices described there. Never use anything marked as deprecated.
+- Always link component names to their reference pages, e.g.: `[`otelcol.exporter.otlphttp`][otelcol.exporter.otlphttp]` with a reference definition at the bottom of the file.
+
+## Create Alloy configuration
+
+Before writing the page, create a working Alloy configuration that satisfies the user's requirements:
+
+1. Identify which Alloy components are needed for the task.
+2. Draft the configuration, then validate it (see **Addendum: Validate Alloy configuration**).
+3. Show the validated config to the user and ask them to confirm it makes sense before proceeding to write the page.
+
+## Create the page
+
+Each task page follows this section order:
+
+### Introductory paragraph
+
+- 1–2 sentences that state what the page helps the user accomplish.
+- No heading — this is the opening paragraph directly under the page `h1`.
+- Example: _"{{< param "PRODUCT_NAME" >}} can receive OpenTelemetry metrics, logs, and traces and forward them to any OTLP-compatible endpoint."_
+
+### Configuration
+
+- Start with an inline SVG pipeline diagram (see **Addendum: generating the pipeline diagram** at the end of this file).
+- Follow the diagram with a single sentence that describes what the configuration does, ending with a **period** (not a colon).
+  - Example: _"The following configuration receives OTLP data from your applications, batches it, and exports it over HTTP."_
+- Then include the full working Alloy config block (already validated in **Create Alloy configuration** above).
+- Use `//` comments inside the config to explain every block and argument — do **not** repeat them as prose bullet lists below the block.
+- Add a blank line between commented arguments; omit blank lines between uncommented ones.
+
+### How it works
+
+- Numbered list with one item per component used in the configuration.
+- Each item links the component name to its reference doc.
+- Keep each item to one sentence.
+
+### Additional sections
+
+Before writing a new page, ask the user: "Are there any additional sections you'd like to add, and what content should they cover?"
+
+## Link to the task page from each component reference doc
+
+Examples live in `docs/sources/monitor-applications/` and `docs/sources/monitor-infrastructure/`, not in component reference docs.
+
+When you create a new task page, for each component it uses:
+
+1. Open the component's reference doc in `docs/sources/reference/components/`.
+2. Find the `## Example` or `## Examples` section. Rename it to `## Examples` if it isn't already plural.
+3. Remove all existing example code and prose from that section.
+4. Replace the content with a bullet list linking to the relevant task pages.
+
+The relative path from a component reference doc to a task page is:
+```
+../../../../monitor-applications/<page-slug>/
+../../../../monitor-infrastructure/<page-slug>/
+```
+
+Example:
+```markdown
+## Examples
+
+- [Collect OpenTelemetry data and forward it to a Grafana database](../../../../monitor-applications/opentelemetry-data/)
+```
+
+---
+
+## Addendum
+
+### Validate Alloy configuration
+
+Run `alloy fmt` on the configuration before publishing. It normalises indentation (tabs) and spacing between blocks, and will error on invalid syntax.
+
+```sh
+./build/alloy fmt <file>.alloy
+```
+
+If the binary isn't built yet:
+
+```sh
+SKIP_UI_BUILD=1 make alloy
+```
+
+### Generating the pipeline diagram
+
+<!-- TODO: replace this addendum seciton with a link to a README in internal/web/ui/scripts/alloy-graph/ once one exists. Also find a way to embed the diagram without inlining raw SVG — the current approach is a workaround for Hugo not serving co-located files for non-bundle pages. -->
+
+Generate an SVG using the `alloy-graph` tool and embed it inline at the top of the Configuration section.
+
+**Generate:**
+```sh
+# From the repo root — install dependencies first if needed
+npm install --prefix internal/web/ui
+
+# Write the config to a temp file, then run:
+npm run graph --prefix internal/web/ui -- <config.alloy>
+```
+
+**Embed the output inline:**
+```markdown
+<svg xmlns="http://www.w3.org/2000/svg" width="100%" viewBox="-2 -2 <W+4> <H+4>" role="img" aria-label="Pipeline diagram: <brief description>">
+  <!-- paste SVG body here -->
+</svg>
+```
+
+The tool outputs `viewBox="0 0 W H"` which clips the 1.5px node stroke. Always expand by 2px on each side: origin `-2 -2`, width `W+4`, height `H+4`.

docs/Makefile

@@ -15,7 +15,7 @@ docs: check-cloudwatch-integration
 endif
 
 check-cloudwatch-integration:
-	$(PODMAN) run -v "$(shell git rev-parse --show-toplevel):/repo:z" -v "$(shell pwd):/docs:z" -w /repo golang:1.25.7-bullseye go run internal/static/integrations/cloudwatch_exporter/docs/doc.go check /docs/sources/reference/components/prometheus/prometheus.exporter.cloudwatch.md
+	$(PODMAN) run -v "$(shell git rev-parse --show-toplevel):/repo:z" -v "$(shell pwd):/docs:z" -w /repo golang:1.25.8-bookworm go run internal/static/integrations/cloudwatch_exporter/docs/doc.go check /docs/sources/reference/components/prometheus/prometheus.exporter.cloudwatch.md
 
 generate-cloudwatch-integration:
-	$(PODMAN) run -v "$(shell git rev-parse --show-toplevel):/repo:z" -v "$(shell pwd):/docs:z" -w /repo golang:1.25.7-bullseye go run internal/static/integrations/cloudwatch_exporter/docs/doc.go generate
+	$(PODMAN) run -v "$(shell git rev-parse --show-toplevel):/repo:z" -v "$(shell pwd):/docs:z" -w /repo golang:1.25.8-bookworm go run internal/static/integrations/cloudwatch_exporter/docs/doc.go generate

docs/make-docs

@@ -8,6 +8,28 @@
 # [Semantic versioning](https://semver.org/) is used to help the reader identify the significance of changes.
 # Changes are relevant to this script and the support docs.mk GNU Make interface.
 #
+# ## 10.1.1 (2026-03-17)
+#
+# ### Fixed
+#
+# - Run Vale non-interactively to enable Claude Code (and similar) to run the tool.
+#
+# ## 10.1.0 (2025-11-11)
+#
+# ### Fixed
+#
+# - Extend readiness probes to prevent confusing output.
+#
+#   Before, the probes could fail too soon and long an error message which contradicted the service starting up.
+#
+# ## 10.0.0 (2025-10-13)
+#
+# ### Changed
+#
+# - Hugo no longer supports the `--debug` option, use `--logLevel debug` instead.
+#
+#   Thank you to @karlskewes for their contribution!
+#
 # ## 9.0.0 (2025-04-05)
 #
 # ### Removed
@@ -724,6 +746,10 @@ await_build() {
   url="$1"
   req="$(if command -v curl >/dev/null 2>&1; then echo 'curl -s -o /dev/null'; else echo 'wget -q'; fi)"
 
+  # Initial delay to allow container to start before beginning healthchecks
+  sleep 3
+
+  # Fast retries for initial startup (10 attempts, 1 second apart)
   i=1
   max=10
   while [ "${i}" -ne "${max}" ]
@@ -752,6 +778,37 @@ POSIX_HERESTRING
     fi
   done
 
+  # Continue checking with longer intervals for slower builds
+  # This prevents false positives for large builds that take longer to start
+  i=1
+  max=20
+  while [ "${i}" -ne "${max}" ]
+  do
+    sleep 2
+    debg "Continuing to check web server (build may be taking longer than expected)."
+    i=$((i + 1))
+
+    if ${req} "${url}"; then
+      printf '\r\nView documentation locally:\r\n'
+      for x in ${url_src_dst_vers}; do
+        IFS='^' read -r url _ _ <<POSIX_HERESTRING
+$x
+POSIX_HERESTRING
+
+        if [ -n "${url}" ]; then
+          if [ "${url}" != arbitrary ]; then
+            printf '\r  %s\r\n' "${url}"
+          fi
+        fi
+      done
+      printf '\r\nPress Ctrl+C to stop the server\r\n'
+
+      unset i max req url
+      return
+    fi
+  done
+
+  # Only log error after extended checking period (total ~60 seconds)
   printf '\r\n'
   errr 'The build was interrupted or a build error occurred, check the previous logs for possible causes.'
   note 'You might need to use Ctrl+C to end the process.'
@@ -845,7 +902,6 @@ case "${image}" in
     IFS='' read -r cmd <<EOF
     ${PODMAN} run \
                 --init \
-                --interactive \
                 --rm \
                 --workdir /etc/vale \
                 --tty \
@@ -952,4 +1008,4 @@ EOF
               -e '/"docs\/_index.md" not found/d'
     fi
     ;;
-esac
+esac

docs/sources/collect/azure-event-hubs-logs.md

@@ -6,6 +6,7 @@ title: Collect Azure Event Hubs logs and forward them to Loki
 weight: 300
 ---
 
+<!-- TODO: move this doc to the Monitor Applications section -->
 # Collect Azure Event Hubs logs and forward them to Loki
 
 You can configure {{< param "PRODUCT_NAME" >}} to collect logs from Azure Event Hubs and forward them to Loki.

docs/sources/collect/ecs-opentelemetry-data.md

@@ -8,6 +8,7 @@ title: Collect Amazon Elastic Container Service or AWS Fargate OpenTelemetry dat
 weight: 500
 ---
 
+<!-- TODO: move this doc to the Monitor Applications section -->
 # Collect Amazon Elastic Container Service or AWS Fargate OpenTelemetry data
 
 You can configure {{< param "FULL_PRODUCT_NAME" >}} or AWS ADOT to collect OpenTelemetry-compatible data from Amazon Elastic Container Service (ECS) or AWS Fargate and forward it to any OpenTelemetry-compatible endpoint.

docs/sources/collect/logs-in-kubernetes.md

@@ -8,6 +8,7 @@ title:  Collect Kubernetes logs and forward them to Loki
 weight: 250
 ---
 
+<!-- TODO: move this doc to the Monitor Applications section -->
 # Collect Kubernetes logs and forward them to Loki
 
 You can configure {{< param "PRODUCT_NAME" >}} to collect logs and forward them to a [Loki][] database.