Footnote behavior and options

[craterlet]

Intro

Thanks for the great project! It has made getting started very easy for a non-developer like me. I've run into just one problem I can't seem to find a solution for.

I am in the early stages of converting large technical document from Word (the format in which it is published by a state government) to a Docusaurus static website for use within my organization. The source document is split into volumes, numbered sections, and numbered sub-sections. As I've been converting this, I've broken out each subsection into its own markdown document.

Problem

The problem I've encountered is that the number sequence used for the footnotes in the original document are continuous for each volume. So, ideally I would be able to have a distinct page in the rendered webpage start with, say, footnote 14 rather than 1.

This seemed to be the behavior I was getting for a few days, but now my footnote lists (at the bottom of the document) are always ordered from 1. Based on what I've read online, this appears to be expected behavior. Is that correct?

The other thing I've discovered is that the inline references are NOT auto numbered. So

// A note[^8]. And another note.[^9] Final test.[^10]

// [^8]: Note eight.
// [^9]: Note nine.
// [^10]: Note ten.

gets rendered as

Is having the mismatch between footnote numbering expected unless they are matched manually?

Desired Outcome

1. The real goal is for the ordered list of footnotes that gets generated at the end of the document to respect the inline numbering. I've read online that this is possible to brute force with CSS by restarting the numbering of the list. It would still just be sequential, but I could set the starting point. Any pointers on how to do this, if it is possible, would be great.
2. A backup solution would be to have the inline references use the same auto-generated numbers that are used at the end. That way, note 1 would visually (not just in terms of the HTML link) point to the correct reference.

Thank you in advance for any insight you might offer!

[slorber]

Thanks

I'm not very experienced with footnotes, but what I understand is that in ^xyz, xyz is an identifier that doesn't have to be a number. Indeed we often use numbers but there's no strict guarantee.

Now you could technically replace the default <li> component that MDX uses for footnotes with your own custom implementation, where you can decide to not show the default <li> numbering.

See how to replace the default li component here: https://docusaurus.io/docs/markdown-features/react#mdx-component-scope

This requires using some tricks because you don't want to change ALL the markdown<li>, but probably just the footnote ones. This means you'd have to inspect a bit the JSX elements to try to detect when it's a footnote list item.

FYI this is what a footnote JSX tree looks like after being compiled by MDX 1:

<ol parentName="div">
  <li
    parentName="ol"
    {...{
      id: "fn-8",
    }}
  >
    {`Note eight.`}
    <a
      parentName="li"
      {...{
        href: "#fnref-8",
        className: "footnote-backref",
      }}
    >{`↩`}</a>
  </li>
  <li
    parentName="ol"
    {...{
      id: "fn-9",
    }}
  >
    {`Note nine.`}
    <a
      parentName="li"
      {...{
        href: "#fnref-9",
        className: "footnote-backref",
      }}
    >{`↩`}</a>
  </li>
  <li
    parentName="ol"
    {...{
      id: "fn-10",
    }}
  >
    {`Note ten.`}
    <a
      parentName="li"
      {...{
        href: "#fnref-10",
        className: "footnote-backref",
      }}
    >{`↩`}</a>
  </li>
</ol>;

https://mdx-git-renovate-babel-monorepo-mdx.vercel.app/playground/

I guess props.id.startsWith("fn-") would be good enough.

---

This is what GitHub renders for

A note[^8]. And another note.[^9] Final test.[^10]

[^8]: Note eight.
[^9]: Note nine.
[^10]: Note ten.

A note¹. And another note.² Final test.³

As you can see, it looks consistent with Docusaurus

Footnotes

1. Note eight. ↩

2. Note nine. ↩

3. Note ten. ↩

[pranabdas]

@slorber Docusaurus and GitHub renderings are not the same. Docusaurus shows:

Unlike GitHub, Docusaurus number of the handles (8, 9, 10 in this case) in the text do not match the numbers in the footnote list.

[slorber]

Yes, good catch. Seems fixed for MDX 2 with remark-gfm, see #7848 (reply in thread)

[RieksJ]

Here is how it works. You can have any text in your footnote ref, so (as @slorber mentioned) [^xyz] works. The footnotes themselves are then simply gathered from the beginning to the end of the document, and put in a numbered, ordered list. That's where they get the number from (starting at 1), and that's also where the ref itself (xyz) gets lost.

It would be nicer if the footnotes were not placed in an ordered list, but in a table (without lines within or around them), where the first column would have the ref (e.g. xyz), and the second column the associated text.

[slorber]

It would be nicer if the footnotes were not placed in an ordered list, but in a table (without lines within or around them), where the first column would have the ref (e.g. xyz), and the second column the associated text.

Makes sense to me.

At the same time it's MDX (v1) that choose to use an ordered list and not display the footnote ref, so I suggest opening an issue on MDX instead and see what they say, this might also be fixed in newer versions? cc https://github.com/wooorm

https://mdx-git-renovate-babel-monorepo-mdx.vercel.app/playground/

---

Edit: Now using the v2 MDX playground with remark-gfm plugin enabled, it seems to render the footnotes like GitHub properly.

https://mdxjs.com/playground/

So I guess we should just upgrade to MDX 2 (asap) and this would be good enough

[RieksJ]

Thanks for responding. I'm not a very tech oriented user of docusaurus, so could you provide me with pointers that enable me to update to MDX 2?

[slorber]

@RieksJ you don't upgrade to MDX 2, we will do this as part of #4029 as soon as we have time, it's in the todolist

In the meantime you can try https://github.com/pomber/docusaurus-mdx-2 but it's not maintained by us, may not work or be fragile. If you are not technical I'd recommend to just wait