Allow heading permalink levels to be configurable (#519)

.phpstorm.meta.php

@@ -27,7 +27,7 @@
     expectedArguments(\League\CommonMark\Node\Inline\Newline::__construct(), 0, argumentsSet('league_commonmark_newline_types'));
     expectedReturnValues(\League\CommonMark\Node\Inline\Newline::getType(), argumentsSet('league_commonmark_newline_types'));
 
-    registerArgumentsSet('league_commonmark_options', 'renderer', 'renderer/block_separator', 'renderer/inner_separator', 'renderer/soft_break', 'enable_em', 'enable_strong', 'use_asterisk', 'use_underscore', 'unordered_list_markers', 'html_input', 'allow_unsafe_links', 'max_nesting_level', 'disallowed_raw_html', 'disallowed_raw_html/disallowed_tags', 'external_link', 'external_link/nofollow', 'external_link/noopener', 'external_link/noreferrer', 'footnote', 'footnote/backref_class', 'footnote/container_add_hr', 'footnote/container_class', 'footnote/ref_class', 'footnote/ref_id_prefix', 'footnote/footnote_class', 'footnote/footnote_id_prefix', 'heading_permalink', 'heading_permalink/html_class', 'heading_permalink/id_prefix', 'heading_permalink/inner_contents', 'heading_permalink/insert', 'heading_permalink/slug_normalizer', 'heading_permalink/symbol', 'heading_permalink/title', 'table_of_contents', 'table_of_contents/style', 'table_of_contents/normalize', 'table_of_contents/position', 'table_of_contents/html_class', 'table_of_contents/min_heading_level', 'table_of_contents/max_heading_level', 'table_of_contents/placeholder');
+    registerArgumentsSet('league_commonmark_options', 'renderer', 'renderer/block_separator', 'renderer/inner_separator', 'renderer/soft_break', 'enable_em', 'enable_strong', 'use_asterisk', 'use_underscore', 'unordered_list_markers', 'html_input', 'allow_unsafe_links', 'max_nesting_level', 'disallowed_raw_html', 'disallowed_raw_html/disallowed_tags', 'external_link', 'external_link/nofollow', 'external_link/noopener', 'external_link/noreferrer', 'footnote', 'footnote/backref_class', 'footnote/container_add_hr', 'footnote/container_class', 'footnote/ref_class', 'footnote/ref_id_prefix', 'footnote/footnote_class', 'footnote/footnote_id_prefix', 'heading_permalink', 'heading_permalink/html_class', 'heading_permalink/id_prefix', 'heading_permalink/inner_contents', 'heading_permalink/insert', 'heading_permalink/max_heading_level', 'heading_permalink/min_heading_level', 'heading_permalink/slug_normalizer', 'heading_permalink/symbol', 'heading_permalink/title', 'table_of_contents', 'table_of_contents/style', 'table_of_contents/normalize', 'table_of_contents/position', 'table_of_contents/html_class', 'table_of_contents/min_heading_level', 'table_of_contents/max_heading_level', 'table_of_contents/placeholder');
     expectedArguments(\League\CommonMark\Environment\EnvironmentInterface::getConfig(), 0, argumentsSet('league_commonmark_options'));
     expectedArguments(\League\CommonMark\Configuration\ConfigurationInterface::get(), 0, argumentsSet('league_commonmark_options'));
     expectedArguments(\League\CommonMark\Configuration\ConfigurationInterface::set(), 0, argumentsSet('league_commonmark_options'));

CHANGELOG.md

@@ -9,6 +9,7 @@ See <https://commonmark.thephpleague.com/2.0/upgrading/> for detailed informatio
 ### Added
 
  - Added the ability to configure disallowed raw HTML tags (#507)
+ - Added `heading_permalink/min_heading_level` and `heading_permalink/max_heading_level` options to control which headings get permalinks (#519)
  - Added new `HtmlFilter` and `StringContainerHelper` utility classes
  - Added new `AbstractBlockContinueParser` class to simplify the creation of custom block parsers
  - Added several new classes and interfaces:

docs/2.0/extensions/heading-permalinks.md

@@ -45,6 +45,8 @@ $config = [
         'html_class' => 'heading-permalink',
         'id_prefix' => 'user-content',
         'insert' => 'before',
+        'min_heading_level' => 1,
+        'max_heading_level' => 6,
         'title' => 'Permalink',
         'symbol' => HeadingPermalinkRenderer::DEFAULT_SYMBOL,
         'slug_normalizer' => new SlugNormalizer(),
@@ -72,6 +74,10 @@ This should be a `string` you want prepended to HTML IDs.  This prevents generat
 
 This controls whether the anchor is added to the beginning of the `<h1>`, `<h2>` etc. tag or to the end.  Can be set to either `'before'` or `'after'`.
 
+### `min_heading_level` and `max_heading_level`
+
+These two settings control which headings should have permalinks added.  By default, all 6 levels (`1`, `2`, `3`, `4`, `5`, and `6`) will have them.  You can override this by setting the `min_heading_level` and/or `max_heading_level` to a different number (`int` value).
+
 ### `symbol`
 
 This option sets the symbol used to display the permalink on the document. This defaults to `\League\CommonMark\Extension\HeadingPermalink\HeadingPermalinkRenderer::DEFAULT_SYMBOL = '¶'`.

src/Extension/HeadingPermalink/HeadingPermalinkProcessor.php

@@ -58,11 +58,14 @@ public function __invoke(DocumentParsedEvent $e): void
     {
         $this->useNormalizerFromConfigurationIfProvided();
 
+        $min = (int) $this->config->get('heading_permalink/min_heading_level', 1);
+        $max = (int) $this->config->get('heading_permalink/max_heading_level', 6);
+
         $walker = $e->getDocument()->walker();
 
         while ($event = $walker->next()) {
             $node = $event->getNode();
-            if ($node instanceof Heading && $event->isEntering()) {
+            if ($node instanceof Heading && $event->isEntering() && $node->getLevel() >= $min && $node->getLevel() <= $max) {
                 $this->addHeadingLink($node);
             }
         }

tests/functional/Extension/HeadingPermalink/HeadingPermalinkExtensionTest.php

@@ -127,4 +127,34 @@ public function testHeadingPermalinksWithInvalidInsertConfigurationValue(): void
         $converter = new CommonMarkConverter($config, $environment);
         $converter->convertToHtml('# This will fail');
     }
+
+    public function testWithCustomLevels(): void
+    {
+        $environment = Environment::createCommonMarkEnvironment();
+        $environment->addExtension(new HeadingPermalinkExtension());
+
+        $config = [
+            'heading_permalink' => [
+                'min_heading_level' => 2,
+                'max_heading_level' => 3,
+            ],
+        ];
+
+        $converter = new CommonMarkConverter($config, $environment);
+
+        $input    = <<<EOT
+# 1
+## 2
+### 3
+#### 4
+EOT;
+        $expected = <<<EOT
+<h1>1</h1>
+<h2><a id="user-content-2" href="#2" name="2" class="heading-permalink" aria-hidden="true" title="Permalink">¶</a>2</h2>
+<h3><a id="user-content-3" href="#3" name="3" class="heading-permalink" aria-hidden="true" title="Permalink">¶</a>3</h3>
+<h4>4</h4>
+EOT;
+
+        $this->assertEquals($expected, \trim($converter->convertToHtml($input)));
+    }
 }