Footnotes numbering

[alexvoss]

The numbering of footnotes follows the order in which the footnotes are defined rather than the order in which they are referenced in the document. This is somewhat surprising.

To reproduce:

#!/usr/bin/env python
import markdown

text = """
# Footnotes ordering

It seems that footnotes appear in the order in which they are
defined[^definedsecond] rather than in the order of their 
occurrence[^definedfirst] in the text.

[^definedfirst]: blah
[^definedsecond]: blurb
"""

print(markdown.markdown(text, extensions=['footnotes']))

(Naively) expected behaviour: the footnotes are numbered 1 then 2 but they come out as 2 then 1.

I do realize that changing the behavior could break things, so perhaps documenting this would be the way to go?

[waylan]

Our documentation states:

Python-Markdown’s Footnote syntax follows the generally accepted syntax of the Markdown community at large and almost exactly matches PHP Markdown Extra’s implementation of footnotes.

We have no intention of changing our behavior when it matches the generally accepted behavior across multiple implementations.

Regarding documenting the behavior, we don't actually document it. Instead we rely on PHP Markdown Extra's documentation to describe the behavior. Whether that should change is a question I have asked from time to time. In the end, we haven't made a change because no-one was willing to do the work. However, if someone was to submit a pull request which included documentation of the full behavior of our extension, I would be willing to review and guide it toward acceptance.

[alexvoss]

Dear Waylan,

thanks for the prompt reply. I appreciate that changing the behavior might not be on the cards. The PHP Markdown Extra documentation states that

—8<— Footnote definitions can be found anywhere in the document, but footnotes will always be listed in the order they are linked to in the text. —8<—

but it does not say anything about the order of the numbering. Going further down the chain to DaringFireball does not help either.

I originally intended to file an issue with MkDocs Material but since I knew that this uses Python Markdown, I thought I’d go one step down in the list of dependencies.

I can do a pull request that documents the current behavior.

Cheers,

Alex

---

Dr Alexander Voss Freelance IT consultant and independent researcher Rights-respecting software engineering @.*** www.corealisation.com

On Aug 2, 2023, at 3:38 PM, Waylan Limberg @.***> wrote:

Our documentation states: Python-Markdown’s Footnote syntax follows the generally accepted syntax of the Markdown community at large and almost exactly matches PHP Markdown Extra’s implementation of footnotes. We have no intention of changing our behavior when it matches the generally accepted behavior across multiple implementations. Regarding documenting the behavior, we don't actually document it. Instead we rely on PHP Markdown Extra's documentation to describe the behavior. Whether that should change is a question I have asked from time to time. In the end, we haven't made a change because no-one was willing to do the work. However, if someone was to submit a pull request which included documentation of the full behavior of our extension, I would be willing to review and guide it toward acceptance. — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you authored the thread.Message ID: @.***>