From a4fb665ca861edb68a5b2bd701a8da27252eb30a Mon Sep 17 00:00:00 2001 From: Mathieu Rochette Date: Sun, 16 Jul 2023 02:33:12 +0200 Subject: [PATCH 1/3] Add TOC in sidebar for PSRs & PERs --- app/config/sculpin_kernel.yml | 12 ++++++ app/lib/CommonMarkEngineFactory.php | 35 ++--------------- app/lib/CommonMarkEnvironmentFactory.php | 42 ++++++++++++++++++++ app/lib/TwigMarkdownTOCExtension.php | 50 ++++++++++++++++++++++++ source/_layouts/psr.twig | 8 ++++ 5 files changed, 116 insertions(+), 31 deletions(-) create mode 100644 app/lib/CommonMarkEnvironmentFactory.php create mode 100644 app/lib/TwigMarkdownTOCExtension.php diff --git a/app/config/sculpin_kernel.yml b/app/config/sculpin_kernel.yml index 1329f059..23eb7aa2 100644 --- a/app/config/sculpin_kernel.yml +++ b/app/config/sculpin_kernel.yml @@ -40,6 +40,13 @@ 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: @@ -47,5 +54,10 @@ services: 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' diff --git a/app/lib/CommonMarkEngineFactory.php b/app/lib/CommonMarkEngineFactory.php index 5aee4508..bbd7ed7a 100644 --- a/app/lib/CommonMarkEngineFactory.php +++ b/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) diff --git a/app/lib/CommonMarkEnvironmentFactory.php b/app/lib/CommonMarkEnvironmentFactory.php new file mode 100644 index 00000000..cf26584b --- /dev/null +++ b/app/lib/CommonMarkEnvironmentFactory.php @@ -0,0 +1,42 @@ + [ + '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; + } +} diff --git a/app/lib/TwigMarkdownTOCExtension.php b/app/lib/TwigMarkdownTOCExtension.php new file mode 100644 index 00000000..931f1829 --- /dev/null +++ b/app/lib/TwigMarkdownTOCExtension.php @@ -0,0 +1,50 @@ +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); + } +} diff --git a/source/_layouts/psr.twig b/source/_layouts/psr.twig index 99071245..21c0d743 100644 --- a/source/_layouts/psr.twig +++ b/source/_layouts/psr.twig @@ -24,6 +24,14 @@ + +
+ +
{% endif %} {% endblock %} From e7ce1fc4f29fd7ec1d2c8b91a01d3d3afb7b4556 Mon Sep 17 00:00:00 2001 From: Mathieu Rochette Date: Sat, 22 Jul 2023 11:24:09 +0200 Subject: [PATCH 2/3] move TOC just below its link in the sidebar --- source/_layouts/psr.twig | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/source/_layouts/psr.twig b/source/_layouts/psr.twig index 21c0d743..2ece4eb8 100644 --- a/source/_layouts/psr.twig +++ b/source/_layouts/psr.twig @@ -19,19 +19,18 @@
  • {{ related.name }} + + {% if related.permalink == '' %} + {% set content = include(page.markdown_source) %} +
    + {{ content | markdown_toc | raw }} +
    + {% endif %}
    • {% endfor %} - -
    - -
    {% endif %} {% endblock %} From 01865a3cd0e1c69c731865cc24393ad9c2c49083 Mon Sep 17 00:00:00 2001 From: Mathieu Rochette Date: Sat, 22 Jul 2023 11:24:59 +0200 Subject: [PATCH 3/3] add CSS for markdown TOC --- source/_sass/all.scss | 1 + source/_sass/blocks/markdown_toc.scss | 18 ++++++++++++++++++ 2 files changed, 19 insertions(+) create mode 100644 source/_sass/blocks/markdown_toc.scss diff --git a/source/_sass/all.scss b/source/_sass/all.scss index 98b2451e..59934597 100644 --- a/source/_sass/all.scss +++ b/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"; diff --git a/source/_sass/blocks/markdown_toc.scss b/source/_sass/blocks/markdown_toc.scss new file mode 100644 index 00000000..4493e373 --- /dev/null +++ b/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; + } +}