From 56d93dbc56487d3dfbe11c948a5b63f993dda70a Mon Sep 17 00:00:00 2001
From: Howard Edwards <howarde.edwards@gmail.com>
Date: Mon, 25 Sep 2023 13:10:52 -0500
Subject: [PATCH] Include clarifying comment

---
 scripts/link-checker.js | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/scripts/link-checker.js b/scripts/link-checker.js
index 001149f9ad..aeab461e74 100644
--- a/scripts/link-checker.js
+++ b/scripts/link-checker.js
@@ -227,6 +227,15 @@ async function checkLinks() {
 
         let matchesHash = true;
         if (hash) {
+          // On some websites, the ids may not exactly match the hash included
+          // in the link.
+          // For e.g. GitHub will prepend client facing ids with their own
+          // calculated value. A heading in a README for example could be
+          // Foo bar, navigated to with https://github.com/foo/bar#foo-bar,
+          // but GitHub calculates the actual markup id included in the document
+          // as being user-content-foo-bar for its own page processing purposes.
+          //
+          // See https://github.com/w3c/aria-practices/issues/2809
           matchesHash = !!matchingPage?.ids.some((id) => id.includes(hash));
         }