From 5b0b118af2a27c9f93ce38cd86ef51f5d5a7837a Mon Sep 17 00:00:00 2001
From: Marcos Caceres <caceres_m@apple.com>
Date: Sat, 28 Mar 2026 16:07:01 +1100
Subject: [PATCH 1/2] fix(mdn): improve key-not-found error hint

Previous hint sent users to a raw JSON URL (non-clickable, hard to read).

New hint:
- Uses docLink so [shortName] and [mdn] are clickable links to the docs
- Explains that mdn: true uses shortName as the key (common confusion)
- Links to GitHub-rendered SPECMAP.json (syntax highlighted, searchable
  with Ctrl+F) instead of the raw URL
- Removes the duplicate of the error message from inside the hint
---
 src/core/mdn-annotation.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/core/mdn-annotation.js b/src/core/mdn-annotation.js
index f94bc2bdab..6fa864f54f 100644
--- a/src/core/mdn-annotation.js
+++ b/src/core/mdn-annotation.js
@@ -1,5 +1,5 @@
 // @ts-check
-import { fetchAndCache, getIntlData, showError } from "./utils.js";
+import { docLink, fetchAndCache, getIntlData, showError } from "./utils.js";
 import css from "../styles/mdn-annotation.css.js";
 import { html } from "./import-maps.js";
 
@@ -177,7 +177,7 @@ async function getMdnData(key, mdnConf) {
   const res = await fetchAndCache(url, maxAge);
   if (res.status === 404) {
     const msg = `Could not find MDN data associated with key "${key}".`;
-    const hint = "Please add a valid key to `respecConfig.mdn`";
+    const hint = docLink`If using \`mdn: true\`, check that ${"[shortName]"} is set correctly — the MDN key defaults to the spec's shortName. Otherwise, search for your spec's URL in the [MDN spec links map](https://github.com/w3c/mdn-spec-links/blob/main/SPECMAP.json) to find the correct key, then set ${"[mdn]"} to it.`;
     showError(msg, name, { hint });
     return;
   }

From 7616c07b2d12657183ae192267b2d3d7ad6c2f8c Mon Sep 17 00:00:00 2001
From: Marcos Caceres <caceres_m@apple.com>
Date: Sun, 29 Mar 2026 00:53:30 +1100
Subject: [PATCH 2/2] test(mdn-annotation): add test for 404 key-not-found hint

---
 tests/spec/core/mdn-annotation-spec.js | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/tests/spec/core/mdn-annotation-spec.js b/tests/spec/core/mdn-annotation-spec.js
index 91bc1c3157..8c0b494602 100644
--- a/tests/spec/core/mdn-annotation-spec.js
+++ b/tests/spec/core/mdn-annotation-spec.js
@@ -116,4 +116,19 @@ describe("Core - MDN Annotation", () => {
     expect(tagName).toBe("ASIDE");
     expect(classList).toContain("mdn");
   });
+
+  it("shows a helpful hint when the mdn key is not found (404)", async () => {
+    const ops = makeStandardOps({
+      mdn: { baseJsonPath },
+      shortName: "nonexistent-spec-xyz",
+    });
+    const doc = await makeRSDoc(ops, "spec/core/mdn-annotation.html");
+    const error = doc.respec.errors.find(
+      e => e.plugin === "core/mdn-annotation"
+    );
+    expect(error).toBeTruthy();
+    expect(error.hint).toContain("SPECMAP.json");
+    expect(error.hint).toContain("shortName");
+    expect(error.hint).toContain("mdn");
+  });
 });