toc: add option to limit which heading levels get anchor links

Author: rundef

docs/extensions/toc.md

@@ -239,18 +239,12 @@ The following options are provided to configure the output:
     Word separator. Character which replaces white space in id. Defaults to "`-`".
 
 * **`toc_depth`**
-    Define the range of section levels to include in the Table of Contents.
-    A single integer (`b`) defines the bottom section level (`<h1>..<hb>`) only.
-    A string consisting of two digits separated by a hyphen in between (`"2-5"`),
-    define the top (`t`) and the bottom (`b`) (`<ht>..<hb>`). Defaults to `6` (bottom).
-
-    When used with conjunction with `baselevel`, this parameter will not
-    take the fitted hierarchy from `baselevel` into account. That is, if
-    both `toc_depth` and `baselevel` are `3`, then only the highest level
-    will be present in the table. If you set `baselevel` to `3` and
-    `toc_depth` to `"2-6"`, the *first* headline will be `<h3>` and so still
-    included in the Table of Contents. To exclude this first level, you
-    have to set `toc_depth` to `"4-6"`.
+    Define the highest heading level (deepest `<hN>`) for which to add anchor links or permalinks.
+    Defaults to `6`
+
+    For example, setting max_level to `2` adds anchors only to `<h1>` and `<h2>` elements.
+
+* **`max_level`**
 
 A trivial example:
 

markdown/extensions/toc.py

@@ -257,7 +257,7 @@ def __init__(self, md: Markdown, config: dict[str, Any]):
         self.permalink_class: str = config["permalink_class"]
         self.permalink_title: str = config["permalink_title"]
         self.permalink_leading: bool | None = parseBoolValue(config["permalink_leading"], False)
-        self.header_rgx = re.compile("[Hh][123456]")
+        self.header_rgx = re.compile(f'[Hh][1-{config["max_level"]}')
         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('-')]
         else:
@@ -466,6 +466,11 @@ def __init__(self, **kwargs):
                 'separated by a hyphen in between (`2-5`) defines the top (t) and the bottom (b) (<ht>..<hb>). '
                 'Default: `6` (bottom).'
             ],
+            'max_level': [
+                6,
+                'Define the max heading level for which to add anchors/permalinks.'
+                'Default: `6`'
+            ]
         }
         """ Default configuration options. """
 

tests/test_syntax/extensions/test_toc.py

@@ -555,6 +555,24 @@ def testAnchorLinkWithDoubleInlineCode(self):
             extensions=[TocExtension(anchorlink=True)]
         )
 
+    def testAnchorLinkWithMaxLevel(self):
+        self.assertMarkdownRenders(
+            self.dedent(
+                '''
+                # Header 1
+
+                ## Header *2*
+                '''
+            ),
+            self.dedent(
+                '''
+                <h1 id="header-1"><a class="toclink" href="#header-1">Header 1</a></h1>
+                <h2 id="header-2">Header <em>2</em></h2>
+                '''
+            ),
+            extensions=[TocExtension(anchorlink=True, max_level=1)]
+        )
+
     def testPermalink(self):
         self.assertMarkdownRenders(
             '# Header',