om2: Setup mdox formatter for openmetrics spec 2.0 (#2892)

* Setup mdox formatter for openmetrics spec 2.0

Signed-off-by: bwplotka <bwplotka@gmail.com>

* avoid bingo

Signed-off-by: bwplotka <bwplotka@gmail.com>

* fix link

Signed-off-by: bwplotka <bwplotka@gmail.com>

* hard wraps

Signed-off-by: bwplotka <bwplotka@gmail.com>

* fmt

Signed-off-by: bwplotka <bwplotka@gmail.com>

---------

Signed-off-by: bwplotka <bwplotka@gmail.com>

Author: bwplotka

.github/workflows/link-validation.yml

@@ -0,0 +1,17 @@
+name: Markdown Validation
+
+on:
+  pull_request:
+
+jobs:
+  check-md-files:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+    - name: Set up Go
+      uses: actions/setup-go@0a12ed9d6a96ab950c8f026ed9f722fe0da7ef32  # v5.2.0
+      with:
+        go-version: stable
+    - name: Check for broken links
+      run: |
+        make check

.github/workflows/md-validation.yml

@@ -0,0 +1,6 @@
+version: 1
+
+# Don't check external URLs, they can time-out a lot (rate limits).
+validators:
+  - type: ignore
+    regex: http(s|)://.*

.mdox.validator.yaml

@@ -1,3 +1,23 @@
-.PHONY: mdox-check
-mdox-check:
-	@mdox fmt --links.validate --check $$(find . -type d -name node_modules -prune -o -type d -name .next -prune -o -type d -name .git -prune -o -name '*.md' -print)
+# TODO(bwplotka): Add more files to format.
+MD_FILES_TO_FORMAT=docs/specs/om/open_metrics_spec_2_0.md
+
+MDOX="mdox"
+$(MDOX):
+	@go install github.com/bwplotka/mdox@v0.9.0
+
+.PHONY: help
+help: ## Displays help.
+	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n\nTargets:\n"} /^[a-zA-Z_-]+:.*?##/ { printf "  \033[36m%-10s\033[0m %s\n", $$1, $$2 }' $(MAKEFILE_LIST)
+
+.PHONY: fmt
+fmt: ## Format docs.
+fmt: $(MDOX)
+	@echo "Formatting markdown files..."
+	@$(MDOX) fmt --links.validate $(MD_FILES_TO_FORMAT)
+
+.PHONY: check
+check: ## Checks if doc is formatter and links are correct (don't check external links).
+check: $(MDOX)
+	@echo "Checking markdown file formatting and basic links..."
+	@$(MDOX) fmt --links.validate --links.validate.config-file=./.mdox.validator.yaml --check $(MD_FILES_TO_FORMAT) || (echo "🔥 Validation failed, files not formatted or links are broken. Try running 'make fmt' to fix formatting!" && exit 1)
+	@echo "✅ Markdown files correctly formatted"