From cd7665705ef79e6916b56dbf8d466d3087d98b6d Mon Sep 17 00:00:00 2001 From: ysard Date: Thu, 3 Feb 2022 03:39:58 +0100 Subject: [PATCH 1/4] footnotes: Allow to use backlink title without footnote number - The placeholder '{}' is optional. So a user can choose to include or not the footnote number in the backlink text. - The modification is backward compatible with configurations using the old '%d' placeholder. --- docs/extensions/footnotes.md | 4 ++-- markdown/extensions/footnotes.py | 5 ++++- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/extensions/footnotes.md b/docs/extensions/footnotes.md index 0794b7f9f..e3439f63e 100644 --- a/docs/extensions/footnotes.md +++ b/docs/extensions/footnotes.md @@ -88,8 +88,8 @@ The following options are provided to configure the output: * **`BACKLINK_TITLE`**: The text string for the `title` HTML attribute of the footnote definition link. - `%d` will be replaced by the footnote number. Defaults to `Jump back to - footnote %d in the text` + The placeholder `{}` will be replaced by the footnote number. Defaults to + `Jump back to footnote {} in the text`. * **`SEPARATOR`**: The text string used to set the footnote separator. Defaults to `:`. diff --git a/markdown/extensions/footnotes.py b/markdown/extensions/footnotes.py index f6f4c8577..3e37f0557 100644 --- a/markdown/extensions/footnotes.py +++ b/markdown/extensions/footnotes.py @@ -170,6 +170,9 @@ def makeFootnotesDiv(self, root): ol = etree.SubElement(div, "ol") surrogate_parent = etree.Element("div") + # Backward compatibility with old '%d' placeholder + backlink_title = self.getConfig("BACKLINK_TITLE").replace("%d", "{}") + for index, id in enumerate(self.footnotes.keys(), start=1): li = etree.SubElement(ol, "li") li.set("id", self.makeFootnoteId(id)) @@ -185,7 +188,7 @@ def makeFootnotesDiv(self, root): backlink.set("class", "footnote-backref") backlink.set( "title", - self.getConfig("BACKLINK_TITLE") % (index) + backlink_title.format(index) ) backlink.text = FN_BACKLINK_TEXT From bcd4ef5269f37d5d2c4da015648b421ed20088c9 Mon Sep 17 00:00:00 2001 From: ysard Date: Thu, 3 Feb 2022 03:46:30 +0100 Subject: [PATCH 2/4] footnotes: Allow to use custom superscript text - The addition of a new SUPERSCRIPT_TEXT option allows to specify a placeholder receiving the footnote number for the superscript text. --- docs/extensions/footnotes.md | 4 ++++ markdown/extensions/footnotes.py | 8 +++++++- 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/extensions/footnotes.md b/docs/extensions/footnotes.md index e3439f63e..e841a324d 100644 --- a/docs/extensions/footnotes.md +++ b/docs/extensions/footnotes.md @@ -86,6 +86,10 @@ The following options are provided to configure the output: The text string that links from the footnote definition back to the position in the document. Defaults to `↩`. +* **`SUPERSCRIPT_TEXT`**: + The text string that links from the position in the document to the footnote + definition. Defaults to `{}`, i.e. only the footnote's number. + * **`BACKLINK_TITLE`**: The text string for the `title` HTML attribute of the footnote definition link. The placeholder `{}` will be replaced by the footnote number. Defaults to diff --git a/markdown/extensions/footnotes.py b/markdown/extensions/footnotes.py index 3e37f0557..731019590 100644 --- a/markdown/extensions/footnotes.py +++ b/markdown/extensions/footnotes.py @@ -47,6 +47,10 @@ def __init__(self, **kwargs): ["↩", "The text string that links from the footnote " "to the reader's place."], + "SUPERSCRIPT_TEXT": + ["{}", + "The text string that links from the reader's place " + "to the footnote."], "BACKLINK_TITLE": ["Jump back to footnote %d in the text", "The text string used for the title HTML attribute " @@ -306,7 +310,9 @@ def handleMatch(self, m, data): sup.set('id', self.footnotes.makeFootnoteRefId(id, found=True)) a.set('href', '#' + self.footnotes.makeFootnoteId(id)) a.set('class', 'footnote-ref') - a.text = str(list(self.footnotes.footnotes.keys()).index(id) + 1) + a.text = self.footnotes.getConfig("SUPERSCRIPT_TEXT").format( + list(self.footnotes.footnotes.keys()).index(id) + 1 + ) return sup, m.start(0), m.end(0) else: return None, None, None From 2f7a87b5dc6e5ac40493a9d8a9ae4b63056515b8 Mon Sep 17 00:00:00 2001 From: ysard Date: Thu, 3 Feb 2022 17:46:17 +0100 Subject: [PATCH 3/4] footnotes: Add tests #1218 --- .../test_syntax/extensions/test_footnotes.py | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/tests/test_syntax/extensions/test_footnotes.py b/tests/test_syntax/extensions/test_footnotes.py index 1a3a2b0bb..9a6b32a24 100644 --- a/tests/test_syntax/extensions/test_footnotes.py +++ b/tests/test_syntax/extensions/test_footnotes.py @@ -300,3 +300,39 @@ def test_footnote_separator(self): '', extension_configs={'footnotes': {'SEPARATOR': '-'}} ) + + def test_backlink_title(self): + """Test backlink title configuration without placeholder.""" + + self.assertMarkdownRenders( + 'paragraph[^1]\n\n[^1]: A Footnote', + '

paragraph1

\n' + '
\n' + '
\n' + '
    \n' + '
  1. \n' + '

    A Footnote ↩

    \n' + '
    2. \n' + '
\n' + '
', + extension_configs={'footnotes': {'BACKLINK_TITLE': 'Jump back to footnote'}} + ) + + def test_superscript_text(self): + """Test superscript text configuration.""" + + self.assertMarkdownRenders( + 'paragraph[^1]\n\n[^1]: A Footnote', + '

paragraph[1]

\n' + '
\n' + '
\n' + '
    \n' + '
  1. \n' + '

    A Footnote ↩

    \n' + '
    2. \n' + '
\n' + '
', + extension_configs={'footnotes': {'SUPERSCRIPT_TEXT': '[{}]'}} + ) From d122fcb69c0e1d634b683f9dbb1483f1a0423452 Mon Sep 17 00:00:00 2001 From: ysard Date: Thu, 3 Feb 2022 18:08:30 +0100 Subject: [PATCH 4/4] changelog: add #1218 --- docs/change_log/release-3.4.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 docs/change_log/release-3.4.md diff --git a/docs/change_log/release-3.4.md b/docs/change_log/release-3.4.md new file mode 100644 index 000000000..fe235c6d3 --- /dev/null +++ b/docs/change_log/release-3.4.md @@ -0,0 +1,29 @@ +title: Release Notes for v3.4 + +# Python-Markdown 3.4 Release Notes + +Python-Markdown version 3.4 supports Python versions 3.6, 3.7, 3.8, 3.9, 3.10 and +PyPy3. + +## Backwards-incompatible changes + +This release doesn't have any backwards-incompatible changes. + +## New features + +The following new features have been included in the 3.4 release: + +* Some new configuration options have been added to the [footnotes](../extensions/footnotes.md) + extension (#1218): + + * Small refactor of the `BACKLINK_TITLE` option; The use of `format()` instead + of "old" `%d` formatter allows to specify text without the need to have the + number of the footnote in it (like footnotes on Wikipedia for example). + The modification is backward compatible so no configuration change is required. + + * Addition of a new option `SUPERSCRIPT_TEXT` that allows to specify a custom + placeholder for the footnote itself in the text. + Ex: `[{}]` will give [1], `({})` will give (1), + or just by default, the current behavior: 1. + +## Bug fixes