Footnotes: Don't use reference as footnote label

[lehnerpat]

Subject of the issue

While other markdown parsers just number footnotes, MDX uses the reference ID/text of reference-style as label instead of numbers. Additionally, these text labels are only used at the footnote usage (in the body text), while the actual footnotes (at the end of the document) are just numbered using an <ol>.

It would be great if this could be adjusted to follow the conventions of regular markdown parsers.

NB: I've tried looking into the code to see if i can adjust or override this behavior myself, but honestly I couldn't find the place where footnotes are processed :(

Your environment

• MDX packages:
  • "@mdx-js/mdx": "^1.0.10",
  • "@mdx-js/react": "^1.0.6",
• used with:
  • "gatsby": "^2.3.25",
  • "gatsby-mdx": "^0.6.2",
  • node v11.9.0

Steps to reproduce

Parse markdown with reference-style footnotes, for example:

### [Footnotes](https://github.com/markdown-it/markdown-it-footnote)

Footnote 1 link[^first].

Footnote 2 link[^second].

Inline footnote^[Text of inline footnote] definition.

Duplicated footnote reference[^second].

[^first]: Footnote **can have markup**

    and multiple paragraphs.

[^second]: Footnote text.

Expected behaviour

Footnote usages (in body text) and footnote definitions (end of document) should be numbered in order of reference in the text, like markdown-it does in this example.

Screenshot:

Actual behaviour

The reference IDs (first and second in the example above) are used as labels in footnote usages, but footnote definitions are numbered.

You can try this by pasting the example markdown above into the "Try it!" field on mdxjs.com.

Screenshot:

[lehnerpat]

(Just noticed in my example above: MDX doesn't process inline footnotes at all. I don't use those, but would probably be cool if you could support those at some point :) )

[wooorm]

This isn’t really related to MDX but relates to remark instead. See the footnotes option there: https://github.com/remarkjs/remark/tree/master/packages/remark-parse#optionsfootnotes.
You can see the code to parse references here and definitions here.

It would be great if this could be adjusted to follow the conventions of regular markdown parsers.

What are the conventions? What are regular markdown parsers? Because markdown-it-footnotes is a non-standard extension, and there is no standard for footnotes in markdown.

My opinion on syntax extensions is: don’t do it. It doesn’t work everywhere. And I’m really happy that MDX exists. Because components are much better than syntax extensions. Use JSX!

[lehnerpat]

What are the conventions? What are regular markdown parsers? Because markdown-it-footnotes is a non-standard extension, and there is no standard for footnotes in markdown.

My opinion on syntax extensions is: don’t do it. It doesn’t work everywhere. And I’m really happy that MDX exists. Because components are much better than syntax extensions. Use JSX!

But if this is the MDX design philosophy, why does MDX exist? (I can just write all the content in JSX!) And why are footnotes implemented currently if they're not standard? And what is the markdown "standard"?

Edit: No, sorry, I shouldn't be so passive aggressive.

It's a shame that MDX doesn't support footnotes in the way that other parsers do that I'm used to, but hey, I'm just one person.

I do wonder why footnotes were added to MDX in they way they were, but that's mostly my curiosity.

I'm currently considering throwing MDX out of my project and just using plain TSX for all my content, so this isn't blocking for me. Just thought it'd be useful for others too :)

[wooorm]

But if this is the MDX design philosophy, why does MDX exist? (I can just write all the content in JSX!)

I’m not saying that it is the MDX design philosophy. I’m explicitly saying that it is my opinion. MDX is markdown + components. More info can be found on the website.
That’ll show that correct, you can write everything in JSX. But should you? MDX lets you do # markdown over <h1>JSX</h1>, and people are building MDX because they like that.

And why are footnotes implemented currently if they're not standard?

I do wonder why footnotes were added to MDX in they way they were, but that's mostly my curiosity.

Good question! Git history, as you probably saw, doesn’t show much. The way they are added can be researched in remark, as I previously linked to you.

And what is the markdown "standard"?

Nowadays, the answer is either a) commonmark, b) markdown.pl, or c) there is no standard.
There is no standard for footnotes though.

Edit: No, sorry, I shouldn't be so passive aggressive.

Thanks!

It's a shame that MDX doesn't support footnotes in the way that other parsers do that I'm used to, but hey, I'm just one person.

What are you used to, other than markdown-it? I’d also like to add that I am one person as well.

I'm currently considering throwing MDX out of my project

okay

[lehnerpat]

Hokay, updates:

Not throwing MDX out after all. (This was also related to some other issues I was having that have now been solved.)

What are you used to, other than markdown-it?

Some context: I'm migrating a blog from Jekyll to Gatsby, and I want to use gatsby-mdx with that :)
So I'm mostly used to how Jekyll handles markdown, and by default, that's using kramdown. I admit at this point that I had not looked at kramdown's page or documentation before just now, and it describes itself as implementing a superset of markdown.

Good question! Git history, as you probably saw, doesn’t show much. The way they are added can be researched in remark, as I previously linked to you.

Indeed, and thanks for pointing me in the right direction. I poked around a bit more, and wrote a small remark-plugin to change footnotes a bit. That way I realized that the commit you linked really just changed the option with which the remark parser is invoked, and all "real" handling of footnotes happens outside of the MDX package itself.

Unfortunately, the place that turns a footnoteReference into the HTML elements uses the footnoteReference's identifier instead of (what I was expecting) the label. This means I can't easily adjust the output with just a simple remark plugin, but would instead have to rewrite the rendered link (in the HAST or later in React).

I've opened syntax-tree/mdast-util-to-hast#31 to change this, hoping this change makes the HAST output more flexible.

For now, there's nothing really to do in MDX, so I'm closing this issue for now :)

[wooorm]

Not throwing MDX out after all.

I've opened syntax-tree/mdast-util-to-hast#31 to change this

Yay! ✨

So I'm mostly used to how Jekyll handles markdown, and by default, that's using kramdown. I admit at this point that I had not looked at kramdown's page or documentation before just now, and it describes itself as implementing a superset of markdown.

Ahh right! Well, footnotes were implemented in remark like five years ago and they were modelled after kramdown, but nothing ever mentioned inline footnotes back then (and kramdown doesn’t either; btw: remark supports inline footnotes like this: [^inline footnote])

I poked around a bit more, and wrote a small remark-plugin to change footnotes a bit

Oh cool! Good idea! When you’re done please add it to the list of plugins!