Merge pull request #295 from torchbox/fix/code-embed-colour-contrast

Add styles for gists

Author: chris-lawton

docs/front-end/markdown-codehilite.md

@@ -1,7 +1,15 @@
-# Markdown block and codehilite
+# Markdown block, Raw HTML block, Gists and Codehilite
+
+## Markdown block and Codehilite
 
 We make use of the [wagtailmarkdown](https://github.com/torchbox/wagtail-markdown) package to provide a markdown block, whose only purpose is to provide a block to add code with syntax highlighting. We could have opted to use [wagtailcodeblock](https://github.com/FlipperPA/wagtailcodeblock) but using `wagtailmarkdown` allowed us to import existing blog posts already using it.
 
 Using headings, text and other formatting in the markdown block will mean pages are not styled correctly. For this reason we have updated the toolbar options in this block to only show the 'code' block. This is done via a custom `admin.js` script which can be used for any admin JavaScript customisations in the future. It is compiled separately to the main site JavaScript in webpack, and called via `core/wagtail_hooks.py`.
 
-`wagtailmarkdown` allows the use of `codehilite` styles for syntax highlighting, from [pygments](https://pygments.org/styles/). We have made use of two themes from pygments - `monokai` for darkmode, and the `default` styles for light mode. Pygments styles aren't available to install via npm, so they are added in a `vendor` folder inside `static_src/sass`, with `stylelint` entirely disabled. There's a simple nesting rule in the CSS to load the `monokai` styles for `.dark-mode` and the `default` styles for `.light-mode`.
+`wagtailmarkdown` allows the use of `codehilite` styles for syntax highlighting, from [pygments](https://pygments.org/styles/). We have made use of two themes from pygments - `monokai` for darkmode, and the `default` styles for light mode. Pygments styles aren't available to install via npm, so they are added in a `vendor` folder inside `static_src/sass`, with `stylelint` entirely disabled. There's a simple nesting rule in the CSS to load the `monokai` styles for `.dark-mode` and the `default` styles for `.light-mode`. The file has it's own entrypoint in the webpack config and the bundled css is output to `static_compiled/css/codehilite.css`. It is then conditionally loaded in via a custom `has_markdown_block` filter that checks for the presence of the markdown block in the page body.
+
+## Raw HTML block and Gists
+
+In some cases Github Gists are used to display code snippets - we use the RAW HTML block to embed these.
+
+Gists do not use codehilite for their styles, so we have a separate `_gist.scss` file in the `static_src/sass/vendor` folder. This is also conditionally loaded in via a custom `has_gist_block` filter that checks for the presence of the RAW HTML block in the page that that includes 'https://gist.github.com' in the content.

tbx/core/templatetags/util_tags.py

@@ -2,6 +2,7 @@
 from django.utils.text import camel_case_to_spaces, slugify
 
 from tbx.core.utils.models import SocialMediaSettings
+from wagtail.blocks import StreamValue
 
 register = template.Library()
 
@@ -88,3 +89,41 @@ def ifinlist(value, list):
     # cast to strings before testing as this is used for heading levels 2, 3, 4 etc
     stringList = [str(x) for x in list]
     return str(value) in stringList
+
+
+@register.filter(name="has_gist_block")
+def has_gist_block(value):
+    if not isinstance(value, StreamValue):
+        return False
+
+    for block in value.blocks_by_name(block_name="raw_html"):
+        if "https://gist.github.com" in block.value:
+            return True
+
+    # Special case for work page section block as the StreamField blockss are nested within sections
+    for block in value.blocks_by_name(block_name="section"):
+        if "content" not in block.value:
+            continue
+        for sub_block in block.value["content"].blocks_by_name("raw_html"):
+            if "https://gist.github.com" in sub_block.value:
+                return True
+
+    return False
+
+
+@register.filter(name="has_markdown_block")
+def has_markdown_block(value):
+    if not isinstance(value, StreamValue):
+        return False
+
+    if len(value.blocks_by_name(block_name="markdown")):
+        return True
+
+    # Special case for work page section block as the StreamField blockss are nested within sections
+    for block in value.blocks_by_name(block_name="section"):
+        if "content" not in block.value:
+            continue
+        if len(block.value["content"].blocks_by_name("markdown")):
+            return True
+
+    return False

tbx/project_styleguide/templates/patterns/base.html

@@ -31,6 +31,16 @@
 
         <link rel="stylesheet" type="text/css" href="{% static 'css/main.css' %}">
 
+        {# Add syntax highlighting for gists if a gist exists within a raw html streamfield #}
+        {% if page.body|has_gist_block %}
+            <link rel="stylesheet" type="text/css" href="{% static 'css/gist.css' %}">
+        {% endif %}
+
+        {# Add syntax highlighting for code snippets within a code block streamfield (aka markdown block) #}
+        {% if page.body|has_markdown_block %}
+            <link rel="stylesheet" type="text/css" href="{% static 'css/codehilite.css' %}">
+        {% endif %}
+
         {% block extra_css %}{% endblock %}
     </head>
 

tbx/project_styleguide/templates/patterns/molecules/streamfield/blocks/markdown_block.html

@@ -1,4 +1,5 @@
 {% load wagtailmarkdown %}
+
 <div class="grid__markdown markdown-block">
     {# tabindex needed because in order to scroll using the keyboard #}
     <div class="markdown-block__scroller" tabindex="0">

tbx/project_styleguide/templates/patterns/pages/blog/blog_detail.html

@@ -1,5 +1,5 @@
 {% extends "patterns/base_page.html" %}
-{% load wagtailcore_tags wagtailimages_tags static %}
+{% load wagtailcore_tags wagtailimages_tags util_tags static %}
 
 {% block meta_tags %}
     <script>

tbx/project_styleguide/templates/patterns/pages/service/service_page.html

@@ -1,5 +1,5 @@
 {% extends "patterns/base_page.html" %}
-{% load wagtailcore_tags wagtailimages_tags static %}
+{% load wagtailcore_tags wagtailimages_tags %}
 
 {% block content %}
     <div class="grid grid--spacer-large streamfield">

tbx/project_styleguide/templates/patterns/pages/standard/standard_page.html

@@ -1,5 +1,5 @@
 {% extends "patterns/base_page.html" %}
-{% load wagtailcore_tags wagtailimages_tags static %}
+{% load wagtailcore_tags wagtailimages_tags %}
 
 {% block content %}
     <div class="grid grid--spacer-large streamfield">

tbx/project_styleguide/templates/patterns/pages/work/historical_work_page.html

@@ -1,5 +1,5 @@
 {% extends "patterns/pages/work/work_page_base.html" %}
-{% load wagtailcore_tags wagtailimages_tags static %}
+{% load wagtailcore_tags wagtailimages_tags %}
 
 {# The historical work pages did not have a separate intro - so we just loop over the body streamfield to find the intro block(s) #}
 {% block intro %}

tbx/static_src/sass/main.scss

@@ -82,6 +82,3 @@
 @tailwind base;
 @tailwind components;
 @tailwind utilities;
-
-// CSS from external vendors (not available as npm)
-@import 'vendor/codehilite';

tbx/static_src/sass/vendor/_codehilite.scss renamed to tbx/static_src/sass/vendor/codehilite.scss

@@ -1,3 +1,5 @@
+// This file has it's own entry point in webpack and is only included in markdown_block.html
+
 /*!
     Code highlighting generated from Pygments | https://pygments.org/
     | Copyright 2006-2023 by the Pygments team
@@ -8,8 +10,6 @@
 
 /* stylelint-disable */
 
-@use 'config' as *;
-
 .mode-dark {
     pre {
         line-height: 125%;