Add a separate mode to parse footnotes the same way GitHub does by notriddle · Pull Request #654 · pulldown-cmark/pulldown-cmark (original) (raw)

This change is similar to, but a more limited change than, <pulldown-cmark#544>. It changes the syntax, but does not touch the generated HTML or event API.

Motivation

This commit is written with usage in mdBook, rustdoc, and docs.rs in mind.

Having a standard to follow, or at least a public test suite in cmark-gfm [^c], makes it easier to distinguish bugs from features.
It makes sense to commit to following GitHub's behavior specifically, because mdBook chapters and docs.rs README files are often viewed in GitHub preview windows, so any divergence will be very annoying.
If mdBook and docs.rs are going to use this syntax, then rustdoc should, too.
Having both footnote syntaxes use the same API and rendering makes it more feasible for rustdoc to change the syntax over an edition. To introduce a syntax change in a new edition of Rust, we must make rustdoc warn anyone who writes code that will have its meaning change. To do it, run the parser twice in lockstep (with ENABLE_FOOTNOTES on one parser, and ENABLE_GFM_FOOTNOTES on the other), and warn if they diverge.
- Alternatively, run a Crater build with this same code to check if this actually causes widespread breakage.
In particular, using tree rewriting to push the footnotes to the end is not as useful as it sounds, since that's not enough to exactly copy the way GitHub renders footnotes. To do that, you also need to sort the footnotes by the order in which they are referenced, not the order in which they are defined. This type of tree rewriting is also a waste of time if you want "margin note" rendering instead of putting them all at the end.

[^c]: cmark-gfm is under the MIT license, so incorporating parts of its test suite into pulldown-cmark should be fine.