Source-ordering footnote definitions complicates HTML sidenotes

[mattwidmann]

The way that footnotes are currently emitted by pulldown_cmark's parser makes it difficult to format them as sidenotes in HTML. The problem is that FootnoteDefinitions are emitted as soon as they're found in the source text. However, sidenote definitions needs to be emitted in the HTML just after the reference mark so that CSS positioning can move them into the margin, like this:

<p>This is normal text with a sidenote<sup>1</sup><span class="sidenote">This is sidenote content.</span>.</p>

But pulldown_cmark produces the footnote definition too late to make that output possible for a Markdown snippet like this:

This is normal text with a sidenote[^note].

And some intervening text.

[^note]: This is sidenote content.

I've thought of a few workarounds, but they're not ideal:

• Pre-process the source to move all paragraphs starting with [^ to the beginning of the document, so that FootnoteDefinitions are guaranteed to be seen before their references.
• Wrap the parser so that when a FootnoteReference is found, it can hold events in memory until it finds the matching FootnoteDefinition.

I'm not sure of the right way to solve this in the pulldown_cmark library, though. Because a footnote definition can contain more styled content, it seems like the definitions should be treated as a start/end event. The lunamark library for Lua has the writer parse the definition each time it's referenced. That kind of solution might make sense here -- storing the footnote definition's contents and parsing it when it's referenced.

[marcusklaas]

It seems that your second strategy would be the cleanest solution to this problem. I don't think this is something that could be done better within pulldown as opposed to a wrapper as you suggested.

[mattwidmann]

Alright, I'll move ahead with my workarounds. It looks like there is a link reference scanning system in place during the first-pass that might be appropriate for handling footnote definitions, too. But the tricky part is dealing with their inline markup. I think this ordering of events seems reasonable (for the example above, plus a sentence to demonstrate how inline markup could be handled):

Text("This is normal text with a sidenote")
Start(Footnote("note"))
Start(Paragraph)
Text("This is sidenote content. With some ")
Tag::Strong("bold")
Text(" inline styles.")
End(Paragraph)
End(Footnote)