executablebooks / MyST-Parser

An extended commonmark compliant parser, with bridges to docutils/sphinx
https://myst-parser.readthedocs.io
MIT License
708 stars 189 forks source link

Add warning for invalid footnotes reference (and unused definitions) #930

Open asmeurer opened 2 months ago

asmeurer commented 2 months ago

What version of myst-parser are you using?

3.0.1

What version dependencies are you using?

Sphinx 7.2.6 docutils 0.20.1

What operating system are you using?

Mac

Describe the Bug

If a Markdown footnote does not have a corresponding reference in either direction, no warnings are emitted. Compare the equivalent RST and Markdown:

Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_

.. rubric:: Footnotes

.. [#f1] Text of the first footnote.
.. [#f3] Text of the second footnote.
Lorem ipsum [^f1] dolor sit amet ... [^f2]

```{rubric} Footnotes

[^f1]: Text of the first footnote.

[^f3]: Text of the second footnote.


The first one gives two warnings in the build

test.rst:1: ERROR: Too many autonumbered footnote references: only 0 corresponding footnotes available. test.rst:1: ERROR: Unknown target name: "f2".



The second one gives no warnings. The resulting document just has a literal [^f2] in the text. 

### Expected Behavior

An invalid footnote should produce a warning, ideally in both directions, since it is an invalid cross-reference. 

### To Reproduce

_No response_
chrisjsewell commented 2 months ago

The resulting document just has a literal [^f2] in the text.

Note, a problem with this is it is basically an intended part of commonmark; that square brackets [] are parsed as text, if there are no definitions: https://github.com/commonmark/commonmark-spec/issues/702 footnote references are generally treated in the same way, although perhaps you could make the case that [^ is a more explicit syntax, so that we could remove this "lazy evaluation"; it would be a breaking change for myst, but shouldn't affect too many.

chrisjsewell commented 2 months ago

Looking at djot, they do indeed always treat [^...] as a footnote, even if no definition is given: https://djot.net/playground/?text=%5B%5Ea%5D&sourcepos=false

(you'll note in https://github.com/jgm/djot, general shortcut link syntax [...] is removed)

chrisjsewell commented 2 months ago

Thinking about this now actually, perhaps a route to removing the annoying "lazy" behaviour of shortcut link references like [...] for myst, would be to introduce a more "specific" syntax like [=...], e.g.

footnote references are never parsed as text [^footnote]

link shortcuts starting with `[=` are never parsed as text (and the `=` is removed from the link) [=reference]

[^footnote]: This is a footnote

[reference]: https://example.com

goes to:

<p>footnote references are never parsed as text <a id="fnref1" href="#fn1"><sup>1</sup></a></p>
<p>link shortcuts starting with <code>[=</code> are never parsed as text (and the <code>=</code> is removed from the link) <a href="https://example.com">reference</a></p>
<section role="doc-endnotes">
<hr>
<ol>
<li id="fn1">
<p>This is a footnote<a href="#fnref1">↩︎</a></p>
</li>
</ol>
</section>