remark-footnotes ordering/labeling issue

[crazygolem]

When using remark-footnotes with HTML output, the footnotes are output in the order the footnotes are called (this is expected, all books and articles I have seen so far use this convention) but since an HTML ordered list <ol> is used and the footnote labels are not renumbered, the footnote labels in the text and the labels in the footnotes section might not match:

FN1[^2]

FN2[^1]


[^2]: `FN1` label "2"
[^1]: `FN2` label "1"

This behavior seems to be intentional to allow the use of arbitrary labels, like e.g. the common *, †, ‡, but even so using the example in the readme I was not able to make it work (not unexpected as a plain ordered list would just use numbers):

FN1[^*]

FN2[^†]

FN3[^‡]

[^†]: `FN2` label "†"
[^*]: `FN1` label "*"
[^‡]: `FN3` label "‡"

Am I missing a plugin to make it work?

In CSS it seems possible to customize the labels of ordered lists, however in pure HTML I don't think it is possible (the li.value attribute only accepts numbers).

[crazygolem]

I also tried a more contrived example with inline footnotes, and the result is... funny 😄

FN1[^2]

FNI^[`FNI` Inline footnote]

FNL[^word]

FN2[^1]

[^1]: `FN2` numeric label "1"
[^2]: `FN1` numeric label "2"
[^word]: `FNL` non-numeric label "word"
[^3]: Unused footnote label

[crazygolem]

It dawned on me that remark-footnotes's purpose is maybe only to parse the footnotes, not to prepare them for HTML rendering. If that is the case, wooorm's comment makes complete sense to me now:

I like that footnotes have meaningful labels. It allows alpha, roman, or even the typical *, †, ‡, §, |, ¶.

See remark-numbered-footnote-labels (and the project it’s based on, linked there) to use numbers instead.

i.e. to have ordered list output in HTML with the labels corresponding to the list items' numbers, the remark-numbered-footnote-labels plugin should be used (I have not managed to make it work yet, but that is another issue entirely).

And the example in remark-footnotes readme that converts markdown with footnotes to HTML is more to demonstrate that the footnotes are parsed correctly, not that they are output correctly to HTML.

[crazygolem]

Thanks for taking the time to have a look at this thread.

I have seen you making the same point in the comment I keep referring to, and I think that it depends, and there is some context missing to make that point:

If we're talking about the HTML output, and in particular the output you get from the example in remark-footnotes' readme

unified()
  .use(markdown)
  .use(footnotes, {inlineNotes: true})
  .use(remark2rehype)
  .use(format)
  .use(html)
  .process(vfile.readSync('example.md'), function (err, file) {
    if (err) throw err
    console.log(String(file))
  })

the "reasonable defaults" end up pretty much in disaster: you get footnote references that correspond to nothing in the HTML document (or only coincidentally, in the very specific case where you happen to also use consecutive numbers starting from 1 for your labels in the markdown source, and with inline footnotes it gets even more complicated).

If instead we're talking only about the markdown AST, sure the behavior of remark-footnotes is reasonable: you get all the information from the input in the AST, you don't know what should happen next and it's up to the processors down the chain to massage that data as needed.

And I am not saying it has to change or anything, it was just not very clear to me from the beginning that remark-footnotes was just providing the nodes in the AST and didn't do anything for the HTML output.

I have figured now that remark-rehype, or rather mdast-util-to-hast also contains code to handle the footnote nodes (which makes sense, but without looking into it I was under the impression that footnotes would be circumscribed to remark-footnotes and that some generic magic was happening later down to transform that into HTML), and probably the problem is that that plugin does not take into account that the footnote labels don't necessarily correspond to the numbers in the generated HTML numbered list. Or maybe the problem is even later in rehype-stringify which should handle that instead but doesn't (I'm not there yet, I just started looking into remark-rehype).

I have looked a bit into remark-numbered-footnote-labels (which doesn't work with the latest version of remark) but it doesn't do exactly what I want anyway: it renumbers based on the footnote definitions' order, not the references' order. It is still a good start for some inspiration.

My comment about using CSS to style the list numbers was out of place; it would only solve half the problem (styling the footnotes, but not the footnote calls) without some extra support in the unified pipeline or from an ad-hoc script. That would be a nice little feature though, to be able to retain the custom labels from the markdown source in the generated HTML output.

Or use a different project!

:'( I love remark and the unified project, I appreciate and am impressed by all the work done so far but I misunderstood remark-footnotes' purpose in the ecosystem. I think I got this now and am looking around to try and understand where the issue really is and how I could make it work for me.

[wooorm]

I’ve pushed the needed changes to render footnotes very closely to how pandoc renders them: syntax-tree/mdast-util-to-hast@0260f76.

Thanks for bringing this to my attention!

[crazygolem]

Thanks for looking into it. I haven't had time myself to dig much deeper yet.

I made a cursory attempt to upgrade to the new version of mdast-util-to-hast you released and try it out, unfortunately I am not familiar enough with npm to do anything more than basic dependencies management and did not manage to force the use of a specific version of mdast-util-to-hast as a transitive dependency. I will try to find some time this weekend for another attempt.

[wooorm]

You can’t easily do that. yarn has resolutions, which might do it.
Otherwise, remark-rehype is rather small. You could copy/paste that for now and try out the new major of the utility (although it’s also ESM now)

[crazygolem]

Thanks for the hint. I managed to make it work by manually editing the content of my node_modules:

1. Replace the mdast-util-to-hast directory with your new version
2. Edit remark-rehype's package.json and update the version to match the replaced package
3. Edit remark-rehype's index.js to also use ESM imports/exports (this is likely dependent on my build pipeline, but I did not manage to make it work without that)

The result is perfect:

FN1[^2]

FNI^[`FNI` Inline footnote]

FNL[^word]

FN2[^1]

[^1]: `FN2` numeric label "1"
[^2]: `FN1` numeric label "2"
[^word]: `FNL` non-numeric label "word"
[^3]: Unused footnote label