0

I'm preparing documentation for a project using the Sphinx readthedocs theme and Myst.

What I'd like to be able to do within a Myst file is to link to a footnote in another Myst file. For example, something like:

See {ref}`Footnote %s <example.md/footnote-label>` in the {ref}`examples` page.

It would be nice to have the footnote's number substituted for footnote-label, but I'd settle for some way of putting in a link anchor to a footnote.

I have no problem with including links to section headers, anchors, equations, figures, etc. I also have no problems with footnotes within a given Myst-Markdown file. I'm rendering the documentation in HTML.

If there's a way to do this, it's not in the Myst documentation. I know I could do this by anticipating the name of the rendered HTML file; e.g.,

[this footnote](document-base/example.html#footnote-label)

but I'd prefer some method by which Sphinx/Markdown would resolve the reference for me.

Edit:

Following Steve's suggestion, I gave it a try. If I had something like this near the top of the document:

I am writing a paragraph that requires a footnote.[^the-footnote]

(my-footnote)=
[^the-footnote]: This is what a footnote looks like.

More stuff...

The link {ref}`my-footnote` would link to just before the "More stuff...", not to the bottom of the page where the footnote was.

William Seligman
  • 53
  • 4
  • Did you try the [`ref` role](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role)? – Steve Piercy Feb 22 '23 at 05:38
  • In that documentation, there's nothing that seems to apply to footnotes. A footnote is not a section header, and there's no clear place to put an link anchor. – William Seligman Feb 22 '23 at 14:43
  • So... no? Would it hurt to try? – Steve Piercy Feb 23 '23 at 05:42
  • I did. I edited the post with the unsuccessful result. – William Seligman Feb 23 '23 at 09:24
  • I would put the footnotes at the end of the page. – Steve Piercy Feb 24 '23 at 13:49
  • That doesn't solve the problem: The anchor would actually point to the bottom of the main text, just above the page's first footnote; what if there are many footnotes on the page, and the one I wish to cross-reference isn't visible if the user clicks the link and is taken to above the first footnote? Also, for the purposes of markup, it can easily be more viewable/editable in text form if the footnote is defined directly under the paragraph that includes it, even if (in HTML) the footnotes are put at the bottom of the page, or (in LaTeX) the footnotes are at the end of a chapter. – William Seligman Feb 24 '23 at 17:22

2 Answers2

0

It turns out that this questions was essentially already asked and answered:

Sphinx footnotes across pages or equivalent

I can't do what I'd like to do with footnotes across documents, using either Sphinx or Myst.

William Seligman
  • 53
  • 4
  • 1
    That's a very different question, even though it discusses footnotes. I am the author of the answer to which you linked. I answered your question with a tested and verified solution, pulled straight from the documentation that I linked to earlier. – Steve Piercy Feb 25 '23 at 11:29
0

From the documentation of ref:

Labels that aren’t placed before a section title can still be referenced, but you must give the link an explicit title, using this syntax:

:ref:`Link title <label-name>`.

In the file with the footnote, do this:

## Footnotes

(my-footnote)=

[^the-footnote]: This is what a footnote looks like.

In the other file, reference the label:

{ref}`My Title <my-footnote>`.
Steve Piercy
  • 13,693
  • 1
  • 44
  • 57
  • That will link _to the page_ with the footnote, but it won't link to the footnote itself. It will link to the location within the page of the anchor. Even if I put footnote at the end of the page, as you suggest, and put the anchor just before the particular footnote to which I'd like to link, the anchor will point to location in the page just before all of the footnotes on that page. That will take user close to the footnote (maybe), but not to the footnote itself. – William Seligman Mar 05 '23 at 19:38
  • Then put the label before the desired footnote. It is a hack, after all. – Steve Piercy Mar 06 '23 at 03:29