Support custom CSS class on TOC element

docs/change_log/release-3.4.md

@@ -51,6 +51,10 @@ The following new features have been included in the 3.3 release:
       Ex: `[{}]` will give <sup>[1]</sup>, `({})` will give <sup>(1)</sup>,
       or just by default, the current behavior: <sup>1</sup>.
 
+* The [Table of Contents](../extensions/toc.md) extension now accepts a `toc_class`
+  parameter which can be used to set the CSS class(es) on the `<div>` that contains the
+  Table of Contents (#1224).
+
 ## Bug fixes
 
 The following bug fixes are included in the 3.4 release:

docs/extensions/toc.md

@@ -151,6 +151,9 @@ The following options are provided to configure the output:
 * **`title`**:
     Title to insert in the Table of Contents' `<div>`. Defaults to `None`.
 
+* **`toc_class`**:
+    CSS class(es) used for the `<div>` containing the Table of Contents. Defaults to `toc`.
+
 * **`anchorlink`**:
     Set to `True` to cause all headers to link to themselves. Default is `False`.
 

markdown/extensions/toc.py

@@ -160,6 +160,7 @@ def __init__(self, md, config):
         self.base_level = int(config["baselevel"]) - 1
         self.slugify = config["slugify"]
         self.sep = config["separator"]
+        self.toc_class = config["toc_class"]
         self.use_anchors = parseBoolValue(config["anchorlink"])
         self.anchorlink_class = config["anchorlink_class"]
         self.use_permalinks = parseBoolValue(config["permalink"], False)
@@ -239,7 +240,7 @@ def add_permalink(self, c, elem_id):
     def build_toc_div(self, toc_list):
         """ Return a string div given a toc list. """
         div = etree.Element("div")
-        div.attrib["class"] = "toc"
+        div.attrib["class"] = self.toc_class
 
         # Add title to the div
         if self.title:
@@ -328,6 +329,9 @@ def __init__(self, **kwargs):
             "title": ["",
                       "Title to insert into TOC <div> - "
                       "Defaults to an empty string"],
+            "toc_class": ['toc',
+                          'CSS class(es) used for the link. '
+                          'Defaults to "toclink"'],
             "anchorlink": [False,
                            "True if header should be a self link - "
                            "Defaults to False"],

mkdocs.yml

@@ -41,6 +41,7 @@ nav:
   - Test Tools: test_tools.md
   - Contributing to Python-Markdown: contributing.md
   - Change Log: change_log/index.md
+  - Release Notes for v.3.4: change_log/release-3.4.md
   - Release Notes for v.3.3: change_log/release-3.3.md
   - Release Notes for v.3.2: change_log/release-3.2.md
   - Release Notes for v.3.1: change_log/release-3.1.md

tests/test_syntax/extensions/test_toc.py

@@ -569,3 +569,46 @@ def testNl2brCompatibility(self):
             '<p>[TOC]<br />\ntext</p>',
             extensions=[TocExtension(), Nl2BrExtension()]
         )
+
+    def testTOCWithCustomClass(self):
+
+        self.assertMarkdownRenders(
+            self.dedent(
+                '''
+                [TOC]
+                # Header
+                '''
+            ),
+            self.dedent(
+                '''
+                <div class="custom">
+                <ul>
+                <li><a href="#header">Header</a></li>
+                </ul>
+                </div>
+                <h1 id="header">Header</h1>
+                '''
+            ),
+            extensions=[TocExtension(toc_class="custom")]
+        )
+
+    def testTOCWithCustomClasses(self):
+        self.assertMarkdownRenders(
+            self.dedent(
+                '''
+                [TOC]
+                # Header
+                '''
+            ),
+            self.dedent(
+                '''
+                <div class="custom1 custom2">
+                <ul>
+                <li><a href="#header">Header</a></li>
+                </ul>
+                </div>
+                <h1 id="header">Header</h1>
+                '''
+            ),
+            extensions=[TocExtension(toc_class="custom1 custom2")]
+        )