From 5a55839c7c38ea52a2db317249de62d012a82025 Mon Sep 17 00:00:00 2001 From: Waylan Limberg Date: Mon, 3 Nov 2025 12:00:48 -0500 Subject: [PATCH 1/2] Revert the default behavior of `USE_DEFINITION_ORDER` The new behavior introduced in 3.9.0 is experimental and results are inconsistent. It should not have been made the default behavior. Relates to #1561. --- docs/changelog.md | 6 +++++- docs/extensions/footnotes.md | 11 +++++------ markdown/extensions/footnotes.py | 4 +++- tests/test_syntax/extensions/test_footnotes.py | 7 ++++--- 4 files changed, 17 insertions(+), 11 deletions(-) diff --git a/docs/changelog.md b/docs/changelog.md index cd6c8ec82..a086bb121 100644 --- a/docs/changelog.md +++ b/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 diff --git a/docs/extensions/footnotes.md b/docs/extensions/footnotes.md index 7d033478f..a4b78b206 100644 --- a/docs/extensions/footnotes.md +++ b/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: diff --git a/markdown/extensions/footnotes.py b/markdown/extensions/footnotes.py index 13ecf7c22..3f8a1ad13 100644 --- a/markdown/extensions/footnotes.py +++ b/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. """ diff --git a/tests/test_syntax/extensions/test_footnotes.py b/tests/test_syntax/extensions/test_footnotes.py index 070fa27fc..896e1fcdf 100644 --- a/tests/test_syntax/extensions/test_footnotes.py +++ b/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">↩

\n' '\n' '\n' - '' + '', + extension_configs={'footnotes': {'USE_DEFINITION_ORDER': False}} ) def test_footnote_order_tricky(self): From 55df26647c8abfa4bb8705916c3c5a4af78a8996 Mon Sep 17 00:00:00 2001 From: Waylan Limberg Date: Mon, 3 Nov 2025 13:13:55 -0500 Subject: [PATCH 2/2] cleanup --- markdown/extensions/footnotes.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/markdown/extensions/footnotes.py b/markdown/extensions/footnotes.py index 3f8a1ad13..8787e4dc4 100644 --- a/markdown/extensions/footnotes.py +++ b/markdown/extensions/footnotes.py @@ -64,7 +64,7 @@ def __init__(self, **kwargs): ':', 'Footnote separator.' ], 'USE_DEFINITION_ORDER': [ - True, + True, 'Order footnote labels by definition order (True) or by document order (False). ' 'Default: True.' ]