Do not parse markdown footnotes as references

Resolves #2991

Author: Gerrit0

CHANGELOG.md

@@ -7,6 +7,7 @@ title: Changelog
 ### Bug Fixes
 
 - Fixed inconsistent anchors on module pages for re-exports, #2990.
+- Markdown references which appear to be footnotes will no longer be checked for links, #2991.
 
 ## v0.28.9 (2025-08-01)
 

src/lib/converter/comments/textParser.ts

@@ -258,7 +258,13 @@ function checkReference(data: TextParserData): RelativeLink | undefined {
         while (/[ \t]/.test(token.text[lookahead])) {
             ++lookahead;
         }
-        if (token.text[lookahead] === "[") {
+        // #2991, we check that this reference also doesn't look like a footnote reference
+        // as it is unlikely that someone uses that syntax without intending for footnote behavior.
+        // This introduces a problem if someone has an [^ref] and doesn't intend for that to
+        // be interpreted as a footnote, but as a reference, but we can't have it both ways,
+        // and having people rename their reference to not be confused with a footnote isn't a
+        // horrible workaround.
+        if (token.text[lookahead] === "[" && token.text[lookahead + 1] !== "^") {
             while (
                 lookahead < token.text.length &&
                 /[^\n\]]/.test(token.text[lookahead])

src/test/comments.test.ts

@@ -1558,6 +1558,7 @@ describe("Comment Parser", () => {
             * [2]:<./example with space>
             * [3]: https://example.com
             * [4]: #hash
+            * [^footnote]: ./example.md
             */`);
 
         equal(
@@ -1579,7 +1580,7 @@ describe("Comment Parser", () => {
                 },
                 {
                     kind: "text",
-                    text: "\n[3]: https://example.com\n[4]: #hash",
+                    text: "\n[3]: https://example.com\n[4]: #hash\n[^footnote]: ./example.md",
                 },
             ] satisfies CommentDisplayPart[],
         );