Add TOC in sidebar for PSRs & PERs

Author: mathroc

app/config/sculpin_kernel.yml

@@ -40,12 +40,24 @@ services:
     tags:
       - { name: twig.extension }
 
+  fig.website.markdown_toc_extension:
+    class: Fig\Website\TwigMarkdownTOCExtension
+    arguments:
+      $environment: '@League\CommonMark\EnvironmentInterface'
+    tags:
+      - { name: twig.extension }
+
   aptoma.twig.markdown_extension:
     class: Aptoma\Twig\Extension\MarkdownExtension
     arguments:
       $markdownEngine: '@Aptoma\Twig\Extension\MarkdownEngineInterface'
     tags:
       - { name: twig.extension }
 
+  League\CommonMark\EnvironmentInterface:
+    factory: ['Fig\Website\CommonMarkEnvironmentFactory', 'create']
+
   Aptoma\Twig\Extension\MarkdownEngineInterface:
     factory: ['Fig\Website\CommonMarkEngineFactory', 'create']
+    arguments:
+      $environment: '@League\CommonMark\EnvironmentInterface'

app/lib/CommonMarkEngineFactory.php

@@ -4,41 +4,14 @@
 
 use Aptoma\Twig\Extension\MarkdownEngine\PHPLeagueCommonMarkEngine;
 use Aptoma\Twig\Extension\MarkdownEngineInterface;
-use League\CommonMark\Block\Element\FencedCode;
-use League\CommonMark\Block\Element\IndentedCode;
-use League\CommonMark\Environment;
-use League\CommonMark\Extension\HeadingPermalink\HeadingPermalinkExtension;
-use League\CommonMark\Extension\Table\TableExtension;
+use League\CommonMark\EnvironmentInterface;
 use League\CommonMark\GithubFlavoredMarkdownConverter;
-use Spatie\CommonMarkHighlighter\FencedCodeRenderer;
-use Spatie\CommonMarkHighlighter\IndentedCodeRenderer;
 
 class CommonMarkEngineFactory
 {
-    public static function create(): MarkdownEngineInterface
-    {
-        $supportedLanguages = [
-            'php',
-            'http', # inside PSR-7
-        ];
-
-        $config = [
-            'heading_permalink' => [
-                'id_prefix' => '',
-                'fragment_prefix' => '',
-                'insert' => 'after',
-            ],
-        ];
-
-        $environment = Environment::createCommonMarkEnvironment();
-        $environment->mergeConfig($config);
-        $environment
-            ->addExtension(new TableExtension())
-            ->addExtension(new HeadingPermalinkExtension())
-            ->addBlockRenderer(FencedCode::class, new FencedCodeRenderer($supportedLanguages))
-            ->addBlockRenderer(IndentedCode::class, new IndentedCodeRenderer($supportedLanguages))
-        ;
-
+    public static function create(
+        EnvironmentInterface $environment,
+    ): MarkdownEngineInterface {
         return new NullSafeCommonMarkEngine(
             new PHPLeagueCommonMarkEngine(
                 new GithubFlavoredMarkdownConverter([], $environment)

app/lib/CommonMarkEnvironmentFactory.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace Fig\Website;
+
+use League\CommonMark\Block\Element\FencedCode;
+use League\CommonMark\Block\Element\IndentedCode;
+use League\CommonMark\Environment;
+use League\CommonMark\EnvironmentInterface;
+use League\CommonMark\Extension\HeadingPermalink\HeadingPermalinkExtension;
+use League\CommonMark\Extension\Table\TableExtension;
+use Spatie\CommonMarkHighlighter\FencedCodeRenderer;
+use Spatie\CommonMarkHighlighter\IndentedCodeRenderer;
+
+class CommonMarkEnvironmentFactory
+{
+    public static function create(): EnvironmentInterface
+    {
+        $supportedLanguages = [
+            'php',
+            'http', # inside PSR-7
+        ];
+
+        $config = [
+            'heading_permalink' => [
+                'id_prefix' => '',
+                'fragment_prefix' => '',
+                'insert' => 'after',
+            ],
+        ];
+
+        $environment = Environment::createCommonMarkEnvironment();
+        $environment->mergeConfig($config);
+        $environment
+            ->addExtension(new TableExtension())
+            ->addExtension(new HeadingPermalinkExtension())
+            ->addBlockRenderer(FencedCode::class, new FencedCodeRenderer($supportedLanguages))
+            ->addBlockRenderer(IndentedCode::class, new IndentedCodeRenderer($supportedLanguages))
+        ;
+
+        return $environment;
+    }
+}

app/lib/TwigMarkdownTOCExtension.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace Fig\Website;
+
+use League\CommonMark\DocParser;
+use League\CommonMark\DocParserInterface;
+use League\CommonMark\ElementRendererInterface;
+use League\CommonMark\EnvironmentInterface;
+use League\CommonMark\Extension\TableOfContents\TableOfContentsGenerator;
+use League\CommonMark\HtmlRenderer;
+use Twig\Extension\AbstractExtension;
+use Twig\TwigFilter;
+
+class TwigMarkdownTOCExtension extends AbstractExtension
+{
+    private readonly DocParserInterface $docParser;
+    private readonly ElementRendererInterface $htmlRenderer;
+
+    public function __construct(
+        EnvironmentInterface $environment,
+    ) {
+        $this->docParser = new DocParser($environment);
+        $this->htmlRenderer = new HtmlRenderer($environment);
+    }
+
+    public function getFilters()
+    {
+        return [
+            new TwigFilter('markdown_toc', function(string $markdown): string {
+                return $this->renderTOC($markdown);
+            }),
+        ];
+    }
+
+    private function renderTOC(string $markdown): string
+    {
+        $generator = new TableOfContentsGenerator(
+            TableOfContentsGenerator::STYLE_ORDERED,
+            TableOfContentsGenerator::NORMALIZE_RELATIVE,
+            minHeadingLevel: 2,
+            maxHeadingLevel: 3,
+        );
+
+        $toc = $generator->generate($this->docParser->parse($markdown));
+
+        return $toc === null
+            ? ''
+            : $this->htmlRenderer->renderBlock($toc, inTightList: true);
+    }
+}

source/_layouts/psr.twig

@@ -24,6 +24,14 @@
             </ul>
         </nav>
     </div>
+
+    <div class="columns__column columns__column--4 columns__column--padding_left">
+        <nav class="sidebar">
+            <h2 class="sidebar__title">Table of contents:</h2>
+            {% set content = include(page.markdown_source) %}
+            {{ content | markdown_toc | raw }}
+        </nav>
+    </div>
     {% endif %}
 </div>
 {% endblock %}