microsoft
Markdown footnote validation
Does this issue occur when all extensions are disabled?: Yes/No Yes
- VS Code Version: 1.73.1
- OS Version: Windows_NT x64 10.0.19044
Steps to Reproduce:
- Create new markdown file
- Type a text:
text[^1]
[^1]: footnote
- See problems:
(×) No link definition found: '^1' (link.no-such-reference) [Ln 1, Col 6]
I'm sure this needs a more thorough look from someone familiar with the parser, but a quick check suggests that this behavior is the result of a conflict between how reference links are parsed and how link definitions are parsed.
Specifically, link definitions are explicitly not recognized if the reference name starts with a caret. (Note the (?!\^).)
https://github.com/microsoft/vscode-markdown-languageservice/blob/984eeb799db77906dd14115837abba2534890369/src/languageFeatures/documentLinks.ts#L323
Conversely, reference links aren't subject to that exclusion. (Called out here as the "link def".)
https://github.com/microsoft/vscode-markdown-languageservice/blob/984eeb799db77906dd14115837abba2534890369/src/languageFeatures/documentLinks.ts#L295-L313
As a result, footnotes appear to be interpreted as [shorthand]-style reference links which simply happen to start with a caret. But because the matching footnote definition isn't recognized as a link definition, the language service sees this as a link without a definition.
By my read, a fix for this could be as simple as removing (?!\^) from definitionPattern. Unless there's something else in the way, that should allow the parser to find the link definition. It'll still think the footnote is a link, though, and I don't know whether that could cause other issues.
Just for additional context, even though most people's use case for this is footnotes, the following minimal example is parsed fine by commonmark.js (see here)
[^1]
[^1]: /url
However, vscode complains with
No link definition found: '^1'(link.no-such-reference)
footnotes are often used in rich documentation sites powered by mkdocs and the likes. Would be great to see this fixed
a few examples with footnotes that are not captured as a link in the current vscode markdown lsp:
[`Makefile`][makefile][^1]
`make`[^4]
[`text`](url)[^5]
I'm running into this issue as well.
VSCode 1.99.3 Windows 10 No extensions activated.
I use footnotes frequently in my markdown files for additional information, and it is frustrating to have them not recognized.
For now I've just disabled these kinds of warnings by adding this to .vscode/settings.json:
{
"markdown.validate.referenceLinks.enabled": "ignore"
}
Additional Interesting Behavior
When the thing preceding the footnote reference is in inline code, the warning isn't there. In every other situation I've tried, it warns even regardless of if the footnote exists in the file.
e.g.:
`happy`[^1]
sad[^2]
[^1]: Works because of backticks.
[^2]: Fails because no backticks. (Incorrect warning of `No link definition found: '^2'(link.no-such-reference)`)
It looks like that's because it doesn't consider them references.
Proposed Fix Doesn't Work
Unfortunately, @benblank's idea didn't work, though it sounded good to me at first.
(I just tested it by hand-editing the extension in my VSCode install.)
When you remove (?!\^), it does start treating them like link references, but that's actually not a good thing. Because it then tries to verify that the first word that come after the footnote reference point to existing files and whatnot.
You could then, in theory, get around that by putting a . as the first two characters of every footnote (so that it's just referencing the directory that the file is in itself.)
But that's not exactly the best solution. It's not really the behavior we're looking for and adds garbage to the footnotes.
The footnote references need to verify only that a footnote exists in the file (preferably the bottom). Not that the contents represents a link.
@mjbvz I come from vscode#268605 and I'm requesting to work on this issue. could you please do a quick check if anyone is working on this? If not I would give it a go.