Skip to content

Commit

Permalink
Allow heading permalink levels to be configurable (#519)
Browse files Browse the repository at this point in the history
  • Loading branch information
colinodell committed Jul 18, 2020
1 parent 06cebc2 commit f801927
Show file tree
Hide file tree
Showing 5 changed files with 39 additions and 2 deletions.
2 changes: 1 addition & 1 deletion .phpstorm.meta.php
Original file line number Diff line number Diff line change
Expand Up @@ -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/levels', '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'));
Expand Down
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/levels` option 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:
Expand Down
5 changes: 5 additions & 0 deletions docs/2.0/extensions/heading-permalinks.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ $config = [
'html_class' => 'heading-permalink',
'id_prefix' => 'user-content',
'insert' => 'before',
'levels' => [1, 2, 3, 4, 5, 6],
'title' => 'Permalink',
'symbol' => HeadingPermalinkRenderer::DEFAULT_SYMBOL,
'slug_normalizer' => new SlugNormalizer(),
Expand Down Expand Up @@ -72,6 +73,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'`.

### `levels`

This controls which heading levels should get permalinks. For example, if you only want links for `<h1>`, `<h2>`, and `<h3>` tags, you can set this option to `[1, 2, 3]`.

### `symbol`

This option sets the symbol used to display the permalink on the document. This defaults to `\League\CommonMark\Extension\HeadingPermalink\HeadingPermalinkRenderer::DEFAULT_SYMBOL = '¶'`.
Expand Down
4 changes: 3 additions & 1 deletion src/Extension/HeadingPermalink/HeadingPermalinkProcessor.php
Original file line number Diff line number Diff line change
Expand Up @@ -58,11 +58,13 @@ public function __invoke(DocumentParsedEvent $e): void
{
$this->useNormalizerFromConfigurationIfProvided();

$levels = $this->config->get('heading_permalink/levels', [1, 2, 3, 4, 5, 6]);

$walker = $e->getDocument()->walker();

while ($event = $walker->next()) {
$node = $event->getNode();
if ($node instanceof Heading && $event->isEntering()) {
if ($node instanceof Heading && $event->isEntering() && \in_array($node->getLevel(), $levels, true)) {
$this->addHeadingLink($node);
}
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -127,4 +127,33 @@ 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' => [
'levels' => [2, 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)));
}
}

0 comments on commit f801927

Please sign in to comment.