Add config option to support previous behavior

- Don't register FootnoteReorderingProcessor if USE_DEFINITION_ORDER
- Footnote reference numbering follows config
- Test added
- Config option added to docs with note on behavior change in v3.9.0
- Update changelog

Author: aeskildsen

docs/changelog.md

@@ -12,11 +12,16 @@ See the [Contributing Guide](contributing.md) for details.
 
 ## [Unreleased]
 
+### Changed
+
+* Footnotes are now ordered by the occurrence of their references in the document.
+  A new config option for `footnotes`, `USE_DEFINITION_ORDER`, has been added to support
+  restoring the previous behavior of ordering footnotes by the occurrence of definitions.
+
 ### Fixed
 
-* Fix handling of incomplete HTML tags in code spans in Python 3.14.
-* Fix issue with footnote ordering (#1367).
 * Ensure inline processing iterates through elements in document order.
+* Fix handling of incomplete HTML tags in code spans in Python 3.14.
 
 ## [3.8.2] - 2025-06-19
 

docs/extensions/footnotes.md

@@ -98,6 +98,15 @@ The following options are provided to configure the output:
 * **`SEPARATOR`**:
     The text string used to set the footnote separator. Defaults to `:`.
 
+* **`USE_DEFINITION_ORDER`**:
+    Whether to order footnotes by the occurence of footnote definitions
+    in the document. Defaults to `False`.
+
+    Introduced in version 3.9.0, this option allows footnotes to be ordered
+    by the occurence of their definitions in the document, rather than by the
+    order of their references in the text. This was the behavior of
+    previous versions of the extension.
+
 A trivial example:
 
 ```python

markdown/extensions/footnotes.py

@@ -62,6 +62,9 @@ def __init__(self, **kwargs):
             ],
             'SEPARATOR': [
                 ':', 'Footnote separator.'
+            ],
+            'USE_DEFINITION_ORDER': [
+                False, 'Whether to order footnotes by footnote content rather than by footnote label.'
             ]
         }
         """ Default configuration options. """
@@ -96,7 +99,8 @@ def extendMarkdown(self, md):
         # Insert a tree-processor to reorder the footnotes if necessary. This must be after
         # `inline` tree-processor so it can access the footnote reference order
         # (`self.footnote_order`) that gets populated by the `FootnoteInlineProcessor`.
-        md.treeprocessors.register(FootnoteReorderingProcessor(self), 'footnote-reorder', 19)
+        if not self.getConfig("USE_DEFINITION_ORDER"):
+            md.treeprocessors.register(FootnoteReorderingProcessor(self), 'footnote-reorder', 19)
 
         # Insert a tree-processor that will run after inline is done.
         # In this tree-processor we want to check our duplicate footnote tracker
@@ -327,14 +331,19 @@ def handleMatch(self, m: re.Match[str], data: str) -> tuple[etree.Element | None
         if id in self.footnotes.footnotes.keys():
             self.footnotes.addFootnoteRef(id)
 
+            if not self.footnotes.getConfig("USE_DEFINITION_ORDER"):
+                # Order by reference
+                footnote_num = self.footnotes.footnote_order.index(id) + 1
+            else:
+                # Order by definition
+                footnote_num = list(self.footnotes.footnotes.keys()).index(id) + 1
+
             sup = etree.Element("sup")
             a = etree.SubElement(sup, "a")
             sup.set('id', self.footnotes.makeFootnoteRefId(id, found=True))
             a.set('href', '#' + self.footnotes.makeFootnoteId(id))
             a.set('class', 'footnote-ref')
-            a.text = self.footnotes.getConfig("SUPERSCRIPT_TEXT").format(
-                self.footnotes.footnote_order.index(id) + 1
-            )
+            a.text = self.footnotes.getConfig("SUPERSCRIPT_TEXT").format(footnote_num)
             return sup, m.start(0), m.end(0)
         else:
             return None, None, None

tests/test_syntax/extensions/test_footnotes.py

@@ -401,6 +401,37 @@ def test_footnote_order_tricky(self):
             '</div>'
         )
 
+    def test_footnote_order_by_definition(self):
+        """Test that footnotes occur in order of definition occurence when so configured."""
+
+        self.assertMarkdownRenders(
+            self.dedent(
+                """
+                First footnote reference[^last_def]. Second footnote reference[^first_def].
+
+                [^first_def]: First footnote.
+                [^last_def]: Second footnote.
+                """
+            ),
+            '<p>First footnote reference<sup id="fnref:last_def"><a class="footnote-ref" '
+            'href="#fn:last_def">2</a></sup>. Second footnote reference<sup id="fnref:first_def">'
+            '<a class="footnote-ref" href="#fn:first_def">1</a></sup>.</p>\n'
+            '<div class="footnote">\n'
+            '<hr />\n'
+            '<ol>\n'
+            '<li id="fn:first_def">\n'
+            '<p>First footnote.&#160;<a class="footnote-backref" href="#fnref:first_def" '
+            'title="Jump back to footnote 1 in the text">&#8617;</a></p>\n'
+            '</li>\n'
+            '<li id="fn:last_def">\n'
+            '<p>Second footnote.&#160;<a class="footnote-backref" href="#fnref:last_def" '
+            'title="Jump back to footnote 2 in the text">&#8617;</a></p>\n'
+            '</li>\n'
+            '</ol>\n'
+            '</div>',
+            extension_configs={'footnotes': {'USE_DEFINITION_ORDER': True}}
+        )
+
     def test_footnote_reference_within_code_span(self):
         """Test footnote reference within a code span."""