From 805d646822a4f1f7fb59c535ee5d6fd5478f5f75 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Emmanuel=20Ats=C3=A9?=
 <4688434+eatse21@users.noreply.github.com>
Date: Thu, 21 May 2026 14:53:19 +0200
Subject: [PATCH] fix(docs): handle non-ASCII anchors in link validator
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Anchor validation failed for links containing accented characters
(e.g. ./customize-bmad.md#dépannage) because the raw anchor didn't
match the slugified version produced by extractAnchors.

Normalize anchors through decodeURIComponent + headingToAnchor before
comparing, and guard against malformed URI components.
---
 tools/validate-doc-links.js | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/tools/validate-doc-links.js b/tools/validate-doc-links.js
index 167268c90..bce61d9dc 100644
--- a/tools/validate-doc-links.js
+++ b/tools/validate-doc-links.js
@@ -288,8 +288,14 @@ function processFile(filePath) {
     if (anchor) {
       const targetContent = fs.readFileSync(targetFile, 'utf-8');
       const anchors = extractAnchors(targetContent);
+      let normalizedAnchor;
+      try {
+        normalizedAnchor = headingToAnchor(decodeURIComponent(anchor));
+      } catch {
+        normalizedAnchor = headingToAnchor(anchor);
+      }
 
-      if (!anchors.has(anchor)) {
+      if (!anchors.has(anchor) && !anchors.has(normalizedAnchor)) {
         issues.push({
           type: 'broken-anchor',
           linkText,