From 4404b52c81fa9ba160c57b8a0d7f5cef5353feb5 Mon Sep 17 00:00:00 2001
From: Dickson Mwendia <64727760+Dickson-Mwendia@users.noreply.github.com>
Date: Tue, 19 May 2026 10:37:05 +0300
Subject: [PATCH 1/2] Add pull_request trigger and exclude live branch from
 linkchecker

The linkchecker workflow was missing a pull_request trigger, so it never
ran as a PR check. This adds the trigger so broken links are caught
before merging. Also excludes the live branch from push triggers since
links are already validated on main.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .github/workflows/linkchecker.yml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.github/workflows/linkchecker.yml b/.github/workflows/linkchecker.yml
index a14a430..ee26b19 100644
--- a/.github/workflows/linkchecker.yml
+++ b/.github/workflows/linkchecker.yml
@@ -1,7 +1,10 @@
 name: Validate existing links
 
 on:
+  pull_request:
   push:
+    branches-ignore:
+      - live
   repository_dispatch:
   workflow_dispatch:
   schedule:

From d3e148eb56aa636db7f5ff9f2f83293f695b5b4d Mon Sep 17 00:00:00 2001
From: Dickson Mwendia <64727760+Dickson-Mwendia@users.noreply.github.com>
Date: Tue, 19 May 2026 10:37:05 +0300
Subject: [PATCH 2/2] Fix linkchecker: add config file and exclude live branch

- Add .lychee.toml so lychee doesn't mistakenly parse package.json as config
- Pass --config=.lychee.toml explicitly in workflow args
- Remove pull_request trigger (push trigger already covers PR branches)
- Exclude live branch from push triggers (already validated on main)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .github/workflows/linkchecker.yml | 10 +++++++++-
 .lychee.toml                      |  2 ++
 2 files changed, 11 insertions(+), 1 deletion(-)
 create mode 100644 .lychee.toml

diff --git a/.github/workflows/linkchecker.yml b/.github/workflows/linkchecker.yml
index a14a430..c2f5e39 100644
--- a/.github/workflows/linkchecker.yml
+++ b/.github/workflows/linkchecker.yml
@@ -2,6 +2,8 @@ name: Validate existing links
 
 on:
   push:
+    branches-ignore:
+      - live
   repository_dispatch:
   workflow_dispatch:
   schedule:
@@ -16,13 +18,19 @@ jobs:
     steps:
       - uses: actions/checkout@v3
 
+      - name: Resolve root-relative links for checking
+        run: |
+          # Convert root-relative markdown links like [text](/path) to [text](https://learn.microsoft.com/path)
+          # so lychee can validate them. This only modifies the CI checkout copy.
+          find . -name '*.md' -exec sed -i -E 's|\]\(/|\](https://learn.microsoft.com/|g' {} +
+
       - name: Link Checker
         id: lychee
         uses: lycheeverse/lychee-action@master
         env:
           GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
         with:
-          args: --accept=200,429,403,502,503 --verbose --no-progress './**/*.md'
+          args: --config=.lychee.toml --accept=200,429,403,502,503 --verbose --no-progress './**/*.md'
           fail: true
 
       - name: Create Issue From File
diff --git a/.lychee.toml b/.lychee.toml
new file mode 100644
index 0000000..dcf3a7e
--- /dev/null
+++ b/.lychee.toml
@@ -0,0 +1,2 @@
+# Lychee link checker configuration
+# https://github.com/lycheeverse/lychee/blob/master/lychee.example.toml