Skip to content

Commit

Permalink
Merge pull request #295 from torchbox/fix/code-embed-colour-contrast
Browse files Browse the repository at this point in the history
Add styles for gists
  • Loading branch information
chris-lawton authored Aug 5, 2024
2 parents eef7db1 + c038dec commit ce00cad
Show file tree
Hide file tree
Showing 12 changed files with 723 additions and 11 deletions.
12 changes: 10 additions & 2 deletions docs/front-end/markdown-codehilite.md
Original file line number Diff line number Diff line change
@@ -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.
39 changes: 39 additions & 0 deletions tbx/core/templatetags/util_tags.py
Original file line number Diff line number Diff line change
Expand Up @@ -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()

Expand Down Expand Up @@ -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
10 changes: 10 additions & 0 deletions tbx/project_styleguide/templates/patterns/base.html
Original file line number Diff line number Diff line change
Expand Up @@ -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>

Expand Down
Original file line number Diff line number Diff line change
@@ -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">
Expand Down
Original file line number Diff line number Diff line change
@@ -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>
Expand Down
Original file line number Diff line number Diff line change
@@ -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">
Expand Down
Original file line number Diff line number Diff line change
@@ -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">
Expand Down
Original file line number Diff line number Diff line change
@@ -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 %}
Expand Down
3 changes: 0 additions & 3 deletions tbx/static_src/sass/main.scss
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,3 @@
@tailwind base;
@tailwind components;
@tailwind utilities;

// CSS from external vendors (not available as npm)
@import 'vendor/codehilite';
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -8,8 +10,6 @@

/* stylelint-disable */

@use 'config' as *;

.mode-dark {
pre {
line-height: 125%;
Expand Down
Loading

0 comments on commit ce00cad

Please sign in to comment.