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: ***@***.***>

[radiofan]

Hello!
Numbering is really wrong...

I try convert this MD to HTML:

aboba [^1]  
biba [^2]  
boba [^3]  

 - 1
   
    - 1.1 [^4]
   
 - 2
   
    - 2.1 [^5]
   
 - 3
   
    - 3.1 [^6]
   

[^1]: aboba
[^2]: biba
[^3]: boba
[^4]: 1.1
[^5]: 2.1
[^6]: 3.1

I is used correct ascending order, but result of HTML is

<p>aboba <sup class="footnote-ref" id="fnref-1"><a href="#fn-1">4</a></sup><br />
biba <sup class="footnote-ref" id="fnref-2"><a href="#fn-2">5</a></sup><br />
boba <sup class="footnote-ref" id="fnref-3"><a href="#fn-3">6</a></sup>  </p>

<ul>
<li><p>1</p>

<ul>
<li>1.1 <sup class="footnote-ref" id="fnref-4"><a href="#fn-4">1</a></sup></li>
</ul></li>
<li><p>2</p>

<ul>
<li>2.1 <sup class="footnote-ref" id="fnref-5"><a href="#fn-5">2</a></sup></li>
</ul></li>
<li><p>3</p>

<ul>
<li>3.1 <sup class="footnote-ref" id="fnref-6"><a href="#fn-6">3</a></sup></li>
</ul></li>
</ul>

<div class="footnotes">
<hr />
<ol>
<li id="fn-1">
<p>aboba&#160;<a href="#fnref-1" class="footnoteBackLink" title="Jump back to footnote 1 in the text.">&#8617;</a></p>
</li>

<li id="fn-2">
<p>biba&#160;<a href="#fnref-2" class="footnoteBackLink" title="Jump back to footnote 2 in the text.">&#8617;</a></p>
</li>

<li id="fn-3">
<p>boba&#160;<a href="#fnref-3" class="footnoteBackLink" title="Jump back to footnote 3 in the text.">&#8617;</a></p>
</li>

<li id="fn-4">
<p>1.1&#160;<a href="#fnref-4" class="footnoteBackLink" title="Jump back to footnote 4 in the text.">&#8617;</a></p>
</li>

<li id="fn-5">
<p>2.1&#160;<a href="#fnref-5" class="footnoteBackLink" title="Jump back to footnote 5 in the text.">&#8617;</a></p>
</li>

<li id="fn-6">
<p>3.1&#160;<a href="#fnref-6" class="footnoteBackLink" title="Jump back to footnote 6 in the text.">&#8617;</a></p>
</li>
</ol>
</div>

[facelessuser]

I cannot reproduce this issue:

import markdown

print(f'Markdown Version: {markdown.__version__}')
print('-----')

MD = """
aboba [^1]
biba [^2]
boba [^3]

 - 1

    - 1.1 [^4]

 - 2

    - 2.1 [^5]

 - 3

    - 3.1 [^6]


[^1]: aboba
[^2]: biba
[^3]: boba
[^4]: 1.1
[^5]: 2.1
[^6]: 3.1
"""

extensions = ["footnotes"]
extension_configs = {}

print(markdown.markdown(MD, extensions=extensions, extension_configs=extension_configs))

Results:

Markdown Version: 3.7
-----
<p>aboba <sup id="fnref:1"><a class="footnote-ref" href="#fn:1">1</a></sup>
biba <sup id="fnref:2"><a class="footnote-ref" href="#fn:2">2</a></sup>
boba <sup id="fnref:3"><a class="footnote-ref" href="#fn:3">3</a></sup></p>
<ul>
<li>
<p>1</p>
<ul>
<li>1.1 <sup id="fnref:4"><a class="footnote-ref" href="#fn:4">4</a></sup></li>
</ul>
</li>
<li>
<p>2</p>
<ul>
<li>2.1 <sup id="fnref:5"><a class="footnote-ref" href="#fn:5">5</a></sup></li>
</ul>
</li>
<li>
<p>3</p>
<ul>
<li>3.1 <sup id="fnref:6"><a class="footnote-ref" href="#fn:6">6</a></sup></li>
</ul>
</li>
</ul>
<div class="footnote">
<hr />
<ol>
<li id="fn:1">
<p>aboba&#160;<a class="footnote-backref" href="#fnref:1" title="Jump back to footnote 1 in the text">&#8617;</a></p>
</li>
<li id="fn:2">
<p>biba&#160;<a class="footnote-backref" href="#fnref:2" title="Jump back to footnote 2 in the text">&#8617;</a></p>
</li>
<li id="fn:3">
<p>boba&#160;<a class="footnote-backref" href="#fnref:3" title="Jump back to footnote 3 in the text">&#8617;</a></p>
</li>
<li id="fn:4">
<p>1.1&#160;<a class="footnote-backref" href="#fnref:4" title="Jump back to footnote 4 in the text">&#8617;</a></p>
</li>
<li id="fn:5">
<p>2.1&#160;<a class="footnote-backref" href="#fnref:5" title="Jump back to footnote 5 in the text">&#8617;</a></p>
</li>
<li id="fn:6">
<p>3.1&#160;<a class="footnote-backref" href="#fnref:6" title="Jump back to footnote 6 in the text">&#8617;</a></p>
</li>
</ol>
</div>

[radiofan]

Yeah, I need to be more careful. Packet, which i use (md2pdf) include packet markdown2. Not markdown...
Thank You very much. I wouldn't have noticed it without You.

[aeskildsen]

—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<—

When I read that "footnotes will always be listed in the order they are linked to in the text", I expect the following (using terms from the Python Markdown 3.8.2 docs).

• The order of footnote label occurences determines the order in which footnote content is rendered in the list of footnotes.

Current behavior, as @alexvoss said, is the other way round. Here is another example:

import markdown

print(f'Markdown Version: {markdown.__version__}')
print('-----')

MD = """
This points to the first footnote[^first].

This points to the last footnote[^last].

[^last]: This is the content of the last footnote.

[^first]: This is the content of the first footnote.
"""

extensions = ["footnotes"]
extension_configs = {}

print(markdown.markdown(MD, extensions=extensions, extension_configs=extension_configs))

Prints:

Markdown Version: 3.8.2
-----
<p>This points to the first footnote<sup id="fnref:first"><a class="footnote-ref" href="#fn:first">2</a></sup>.</p>
<p>This points to the last footnote<sup id="fnref:last"><a class="footnote-ref" href="#fn:last">1</a></sup>.</p>
<div class="footnote">
<hr />
<ol>
<li id="fn:last">
<p>This is the content of the last footnote.&#160;<a class="footnote-backref" href="#fnref:last" title="Jump back to footnote 1 in the text">&#8617;</a></p>
</li>
<li id="fn:first">
<p>This is the content of the first footnote.&#160;<a class="footnote-backref" href="#fnref:first" title="Jump back to footnote 2 in the text">&#8617;</a></p>
</li>
</ol>
</div>

I don't know how other implementations handle this, but as far as I can tell the behavior doesn't match the docs. I would argue that's a bug.

[facelessuser]

It's possible that PHP Markdown Extras has changed its convention from when this was first implemented here.

This is what it shows for PHP Markdown Extras in BabelMark.

If our claim is to match PHP Markdown Extras, I don't think we exactly do that anymore. If we don't care, we should probably define what we do in the documents. If we do care, then we should adjust to match.

[aeskildsen]

I agree, @facelessuser - thank you for testing this on BabelMark.

I for one find it worthwhile to adjust the behavior to match that of PHP Markdown Extras for a few reasons:

• If another project were to programmatically create footnotes in a markdown document, you would insert the label at the precise point where it should go, and the content/definition you could just tack on to the end of the document. But with the current behavior you have to remove all footnote content definitions and reinsert them in the order that their corresponding labels appear. I'm building a citation processor for mkdocs and would be happy to not have to do that.
• It is the logical behavior I would expect as a writer.

I might be able to make a pull request that adjusts this. Let me know if that would be helpful.

[facelessuser]

I'm not personally against changing the order of the footnotes in relation to linking. It seems that most these days follow this behavior, even PHP Markdown, what this project originally used as a guide, but this would be up to @waylan as the lead maintainer.

[waylan]

Personally, I could care less how footnotes are ordered. However, I understand not everyone will agree with me. That said, I have no interest in spending any time on this. If someone else wants to do the work, they are welcome to.

[facelessuser]

Yeah, I don't have a strong opinion either way. Since this seems to be a topic of confusion for some, at the very least we should update the docs to state this is a difference, but I'm fine if the ordering changed as well.