From 96bc9a73605b9e83da0117a815c43a0caf36d9bb Mon Sep 17 00:00:00 2001
From: Patrice Chalin <chalin@users.noreply.github.com>
Date: Wed, 29 Jan 2025 21:46:25 -0500
Subject: [PATCH] [CI] Report non-normalized link from docs into docs (#1844)

Co-authored-by: Liudmila Molkova <limolkova@microsoft.com>
---
 Makefile | 20 +++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)

diff --git a/Makefile b/Makefile
index 5c2b6b411..5c4a20325 100644
--- a/Makefile
+++ b/Makefile
@@ -5,13 +5,14 @@ PWD := $(shell pwd)
 # Determine OS & Arch for specific OS only tools on Unix based systems
 OS := $(shell uname | tr '[:upper:]' '[:lower:]')
 ifeq ($(OS),darwin)
-	SED := gsed
+	SED ?= gsed
 else
-	SED := sed
+	SED ?= sed
 endif
 
 TOOLS_DIR := $(PWD)/internal/tools
 
+MARKDOWN_LINK_CHECK_ARG= # pass extra arguments such as --exclude '^http'
 MISSPELL_BINARY=bin/misspell
 MISSPELL = $(TOOLS_DIR)/$(MISSPELL_BINARY)
 
@@ -66,14 +67,27 @@ misspell:	$(MISSPELL)
 misspell-correction:	$(MISSPELL)
 	$(MISSPELL) -w $(ALL_DOCS)
 
+.PHONY: normalized-link-check
+# NOTE: we check `model/[a-z]*` to avoid `model/README.md`, which contains
+# valid occurrences of `../docs/`.
+normalized-link-check:
+	@if grep -R '\.\./docs/' docs model/[a-z]*; then \
+		echo "\nERROR: Found occurrences of '../docs/'; see above."; \
+		echo "       Remove the '../docs/' from doc page links referencing doc pages."; \
+		exit 1; \
+	else \
+		echo "Normalized-link check passed."; \
+	fi
+
 .PHONY: markdown-link-check
-markdown-link-check:
+markdown-link-check: normalized-link-check
 	docker run --rm \
 		--mount 'type=bind,source=$(PWD),target=/home/repo' \
 		lycheeverse/lychee \
 		--config home/repo/.lychee.toml \
 		--root-dir /home/repo \
 		--verbose \
+		$(MARKDOWN_LINK_CHECK_ARG) \
 		home/repo
 
 .PHONY: markdown-link-check-changelog-preview