[TableOfContents] Add a label option

By default no label is shown, but if one is set it is added as a `<strong>`
before the first item in the table of contents.

Author: DanielEScherzer

src/Extension/TableOfContents/TableOfContentsBuilder.php

@@ -43,6 +43,7 @@ public function onDocumentParsed(DocumentParsedEvent $event): void
             (int) $this->config->get('table_of_contents/min_heading_level'),
             (int) $this->config->get('table_of_contents/max_heading_level'),
             (string) $this->config->get('heading_permalink/fragment_prefix'),
+            (string) $this->config->get('table_of_contents/label'),
         );
 
         $toc = $generator->generate($document);

src/Extension/TableOfContents/TableOfContentsExtension.php

@@ -35,6 +35,7 @@ public function configureSchema(ConfigurationBuilderInterface $builder): void
             'max_heading_level' => Expect::int()->min(1)->max(6)->default(6),
             'html_class' => Expect::string()->default('table-of-contents'),
             'placeholder' => Expect::anyOf(Expect::string(), Expect::null())->default(null),
+            'label' => Expect::anyOf(Expect::string(), Expect::null())->default(null),
         ]));
     }
 

src/Extension/TableOfContents/TableOfContentsGenerator.php

@@ -18,13 +18,15 @@
 use League\CommonMark\Extension\CommonMark\Node\Block\ListData;
 use League\CommonMark\Extension\CommonMark\Node\Block\ListItem;
 use League\CommonMark\Extension\CommonMark\Node\Inline\Link;
+use League\CommonMark\Extension\CommonMark\Node\Inline\Strong;
 use League\CommonMark\Extension\HeadingPermalink\HeadingPermalink;
 use League\CommonMark\Extension\TableOfContents\Node\TableOfContents;
 use League\CommonMark\Extension\TableOfContents\Normalizer\AsIsNormalizerStrategy;
 use League\CommonMark\Extension\TableOfContents\Normalizer\FlatNormalizerStrategy;
 use League\CommonMark\Extension\TableOfContents\Normalizer\NormalizerStrategyInterface;
 use League\CommonMark\Extension\TableOfContents\Normalizer\RelativeNormalizerStrategy;
 use League\CommonMark\Node\Block\Document;
+use League\CommonMark\Node\Inline\Text;
 use League\CommonMark\Node\NodeIterator;
 use League\CommonMark\Node\RawMarkupContainerInterface;
 use League\CommonMark\Node\StringContainerHelper;
@@ -54,13 +56,17 @@ final class TableOfContentsGenerator implements TableOfContentsGeneratorInterfac
     /** @psalm-readonly */
     private string $fragmentPrefix;
 
-    public function __construct(string $style, string $normalizationStrategy, int $minHeadingLevel, int $maxHeadingLevel, string $fragmentPrefix)
+    /** @psalm-readonly */
+    private string $label;
+
+    public function __construct(string $style, string $normalizationStrategy, int $minHeadingLevel, int $maxHeadingLevel, string $fragmentPrefix, string $label)
     {
         $this->style                 = $style;
         $this->normalizationStrategy = $normalizationStrategy;
         $this->minHeadingLevel       = $minHeadingLevel;
         $this->maxHeadingLevel       = $maxHeadingLevel;
         $this->fragmentPrefix        = $fragmentPrefix;
+        $this->label                 = $label;
 
         if ($fragmentPrefix !== '') {
             $this->fragmentPrefix .= '-';
@@ -111,6 +117,12 @@ public function generate(Document $document): ?TableOfContents
             return null;
         }
 
+        if ($this->label !== '') {
+            $label = new Strong();
+            $label->appendChild(new Text($this->label));
+            $toc->prependChild($label);
+        }
+
         return $toc;
     }
 

tests/functional/Extension/TableOfContents/md/has-label.html

@@ -0,0 +1,11 @@
+<ul class="table-of-contents">
+<strong>Table of Contents</strong>
+<li><a href="#content-hello-world">Hello World!</a>
+<ul>
+<li><a href="#content-isnt-markdown-great">Isn't Markdown Great?</a></li>
+</ul>
+</li>
+</ul>
+<p>This is my document.</p>
+<h1><a id="content-hello-world" href="#content-hello-world" class="heading-permalink" aria-hidden="true" title="Permalink">¶</a>Hello World!</h1>
+<h2><a id="content-isnt-markdown-great" href="#content-isnt-markdown-great" class="heading-permalink" aria-hidden="true" title="Permalink">¶</a>Isn't Markdown Great?</h2>

tests/functional/Extension/TableOfContents/md/has-label.md

@@ -0,0 +1,10 @@
+---
+table_of_contents:
+    label: Table of Contents
+---
+
+This is my document.
+
+# Hello World!
+
+## Isn't Markdown Great?

tests/functional/Extension/TableOfContents/xml/has-label.md

@@ -0,0 +1,10 @@
+---
+table_of_contents:
+    label: Table of Contents
+---
+
+This is my document.
+
+# Hello World!
+
+## Isn't Markdown Great?

tests/functional/Extension/TableOfContents/xml/has-label.xml

@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<document xmlns="http://commonmark.org/xml/1.0">
+    <table_of_contents type="bullet" tight="false">
+        <strong>
+            <text>Table of Contents</text>
+        </strong>
+        <item>
+            <link destination="#content-hello-world" title="">
+                <text>Hello World!</text>
+            </link>
+            <list type="bullet" tight="false">
+                <item>
+                    <link destination="#content-isnt-markdown-great" title="">
+                        <text>Isn't Markdown Great?</text>
+                    </link>
+                </item>
+            </list>
+        </item>
+    </table_of_contents>
+    <paragraph>
+        <text>This is my document.</text>
+    </paragraph>
+    <heading level="1">
+        <heading_permalink slug="hello-world" />
+        <text>Hello World!</text>
+    </heading>
+    <heading level="2">
+        <heading_permalink slug="isnt-markdown-great" />
+        <text>Isn't Markdown Great?</text>
+    </heading>
+</document>