Revert the default behavior of USE_DEFINITION_ORDER

docs/changelog.md

@@ -14,7 +14,11 @@ See the [Contributing Guide](contributing.md) for details.
 
 ### Fixed
 
-* Fix an HTML comment parsing case in some Python versions that can cause an infinite loop (#1554).
+* Fix an HTML comment parsing case in some Python versions that can cause an
+  infinite loop (#1554).
+* Revert the default behavior of `USE_DEFINITION_ORDER` (to `True`). The new
+  behavior introduced in 3.9.0 is experimental and results are inconsistent.
+  It should not have been made the default behavior (#1561).
 
 ## [3.9.0] - 2025-09-04
 

docs/extensions/footnotes.md

@@ -106,13 +106,12 @@ The following options are provided to configure the output:
     The text string used to set the footnote separator. Defaults to `:`.
 
 * **`USE_DEFINITION_ORDER`**:
-    Whether to order footnotes by the occurrence of footnote definitions
-    in the document. Defaults to `False`.
+    Order footnotes by definition order (`True`) or by document order (`False`).
+    Defaults to `True`.
 
-    Introduced in version 3.9.0, this option allows footnotes to be ordered
-    by the occurrence 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.
+    The default behavior matches the behavior prior to this option being added. 
+    Disabling this option (setting to `False`) is experimental and results may not
+    be consistent.
 
 A trivial example:
 

markdown/extensions/footnotes.py

@@ -64,7 +64,9 @@ def __init__(self, **kwargs):
                 ':', 'Footnote separator.'
             ],
             'USE_DEFINITION_ORDER': [
-                False, 'Whether to order footnotes by footnote content rather than by footnote label.'
+                True,
+                'Order footnote labels by definition order (True) or by document order (False). '
+                'Default: True.'
             ]
         }
         """ Default configuration options. """

tests/test_syntax/extensions/test_footnotes.py

@@ -337,8 +337,8 @@ def test_superscript_text(self):
             extension_configs={'footnotes': {'SUPERSCRIPT_TEXT': '[{}]'}}
         )
 
-    def test_footnote_order(self):
-        """Test that footnotes occur in order of reference appearance."""
+    def test_footnote_order_by_doc_order(self):
+        """Test that footnotes occur in order of reference appearance when so configured."""
 
         self.assertMarkdownRenders(
             self.dedent(
@@ -364,7 +364,8 @@ def test_footnote_order(self):
             'title="Jump back to footnote 2 in the text">&#8617;</a></p>\n'
             '</li>\n'
             '</ol>\n'
-            '</div>'
+            '</div>',
+            extension_configs={'footnotes': {'USE_DEFINITION_ORDER': False}}
         )
 
     def test_footnote_order_tricky(self):