Add TOC in sidebar for PSRs & PERs

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

@@ -19,6 +19,13 @@
                     <li class="sidebar__item">
                         <a class="sidebar__link {% if related.permalink == '' %}sidebar__link--active{% endif %}"
                            href="{{ related.permalink }}">{{ related.name }}</a>
+
+                        {% if related.permalink == '' %}
+                            {% set content = include(page.markdown_source) %}
+                            <div class="sidebar_toc markdown">
+                                {{ content | markdown_toc | raw }}
+                            </div>
+                        {% endif %}
                     </li>
                 {% endfor %}
             </ul>

source/_sass/all.scss

@@ -21,6 +21,7 @@
 @import "blocks/home_banner";
 @import "blocks/home_features";
 @import "blocks/markdown";
+@import "blocks/markdown_toc";
 @import "blocks/get_involved_links";
 @import "blocks/faqs";
 @import "blocks/bylaws";

source/_sass/blocks/markdown_toc.scss

@@ -0,0 +1,18 @@
+.markdown.sidebar_toc {
+    ol {
+        list-style-type: none;
+        margin-top: 0;
+
+        li {
+            margin: 0;
+        }
+    }
+
+    & > ol {
+        padding-left: 15px;
+    }
+
+    p {
+        margin-bottom: 0;
+    }
+}