Add permalink_title option (Python-Markdown#886)

Addes a new `permalink_title` option to the TOC extension, which allows the title attribute of a permalink to be set to something other than the default English string "Permanent link". Fixes Python-Markdown#781.
jayaike · Nov 26, 2019 · 6651746 · 6651746
1 parent 1f3ec53
commit 6651746
Show file tree

Hide file tree

Showing 4 changed files with 43 additions and 7 deletions.
diff --git a/docs/change_log/release-3.2.md b/docs/change_log/release-3.2.md
@@ -53,15 +53,23 @@ continue to see the old behavior.
 
 The following new features have been included in the release:
 
-* Two new configuration options have been added to the [toc](../extensions/toc.md)
-  extension: `anchorlink_class` and `permalink_class` which allows class(es) to be
-  assigned to the `anchorlink` and `permalink` HTML respectively. This allows using 
-  icon fonts from CSS for the links. Therefore, an empty string passed to `permalink`
-  now generates an empty `permalink`. Previously no `permalink` would have been
-  generated. (#776)
+* Some new configuration options have been added to the [toc](../extensions/toc.md)
+  extension:
+
+    * The `anchorlink_class` and `permalink_class` options allow class(es) to be
+      assigned to the `anchorlink` and `permalink` respectively. This allows using 
+      icon fonts from CSS for the links. Therefore, an empty string passed to 
+      `permalink` now generates an empty `permalink`. Previously no `permalink` 
+      would have been generated. (#776)
+
+    * The `permalink_title` option allows the title attribute of a `permalink` to be
+      set to something other than the default English string `Permanent link`. (#877)
+
 * Document thread safety (#812).
+
 * Markdown parsing in HTML has been exposed via a separate extension called
   [`md_in_html`](../extensions/md_in_html.md).
+
 * Add support for Python 3.8.
 
 ## Bug fixes

diff --git a/docs/extensions/toc.md b/docs/extensions/toc.md
@@ -168,6 +168,9 @@ The following options are provided to configure the output:
 * **`permalink_class`**:
     CSS class(es) used for the link. Defaults to `headerlink`.
 
+* **`permalink_title`**:
+    Title attribute of the permanent link. Defaults to `Permanent link`.
+
 * **`baselevel`**:
     Base level for headers. Defaults to `1`.
 

diff --git a/markdown/extensions/toc.py b/markdown/extensions/toc.py
@@ -141,6 +141,7 @@ def __init__(self, md, config):
         if self.use_permalinks is None:
             self.use_permalinks = config["permalink"]
         self.permalink_class = config["permalink_class"]
+        self.permalink_title = config["permalink_title"]
         self.header_rgx = re.compile("[Hh][123456]")
         if isinstance(config["toc_depth"], str) and '-' in config["toc_depth"]:
             self.toc_top, self.toc_bottom = [int(x) for x in config["toc_depth"].split('-')]
@@ -201,7 +202,8 @@ def add_permalink(self, c, elem_id):
                           else self.use_permalinks)
         permalink.attrib["href"] = "#" + elem_id
         permalink.attrib["class"] = self.permalink_class
-        permalink.attrib["title"] = "Permanent link"
+        if self.permalink_title:
+            permalink.attrib["title"] = self.permalink_title
         c.append(permalink)
 
     def build_toc_div(self, toc_list):
@@ -306,6 +308,9 @@ def __init__(self, **kwargs):
             "permalink_class": ['headerlink',
                                 'CSS class(es) used for the link. '
                                 'Defaults to "headerlink"'],
+            "permalink_title": ["Permanent link",
+                                "Title attribute of the permalink - "
+                                "Defaults to 'Permanent link'"],
             "baselevel": ['1', 'Base level for headers.'],
             "slugify": [slugify,
                         "Function to generate anchors based on header text - "

diff --git a/tests/test_syntax/extensions/test_toc.py b/tests/test_syntax/extensions/test_toc.py
@@ -99,3 +99,23 @@ def testPermalinkWithCustomClasses(self):
             '</h1>',                                                                           # noqa
             extensions=[TocExtension(permalink=True, permalink_class="custom1 custom2")]
         )
+
+    def testPermalinkWithCustomTitle(self):
+        self.assertMarkdownRenders(
+            '# Header',
+            '<h1 id="header">'                                                    # noqa
+                'Header'                                                          # noqa
+                '<a class="headerlink" href="#header" title="custom">&para;</a>'  # noqa
+            '</h1>',                                                              # noqa
+            extensions=[TocExtension(permalink=True, permalink_title="custom")]
+        )
+
+    def testPermalinkWithEmptyTitle(self):
+        self.assertMarkdownRenders(
+            '# Header',
+            '<h1 id="header">'                                                    # noqa
+                'Header'                                                          # noqa
+                '<a class="headerlink" href="#header">&para;</a>'                 # noqa
+            '</h1>',                                                              # noqa
+            extensions=[TocExtension(permalink=True, permalink_title="")]
+        )