Refactoring my personal website, Part 2: Syntax highlighting

2022-08-26

• Dev-Blog
• Personal-website
• Frontend

Inline syntax highlighting

For inline syntax highlighting, I simply used the <code>-tag and styled it to fit in with the website. One thing to look out for are the margin-top and margin-bottom as well as the padding attributes. If the padding is set without compensating for it by increasing the top and bottom margins, snippets can overlap.

A correct setup, ensures that the padding is compensated for by an increased margin and for this website looks as follows.

#post code {
    background: black;
    color: #fcf9f6;
    padding: .15rem;
    margin: .1rem 0 .1rem 0;
    width: fit-content;
}

Block syntax highlighting with Jekyll and Rouge

For longer snippets more refined highlighting is needed and thus the <code>-tag will no longer suffice.

Luckily Jekyll comes with built in syntax highlighting via Rouge. And, on the contrary to what some articles that I have found while setting this up have claimed, no further configuration in regards to Jekyll is needed (Jekyll 4).

What is needed though is a stylesheet, that tells Jekyll and Rouge what to do whenever a valid {% highlight language %} block is detected. A list of supported languages, including their slugs, which are needed for the command can be found here.

To generate such a style sheet I used this neat tool. The only drawback was that it didn't feature a preview for CSS at the time of writing this article, which meant that some further tweaking was needed.

Specifically, the following classes needed to be updated to style CSS correctly.

/* CSS attributes */
.highlight .nl {
    color: #eed115;
    background-color: transparent;
}

/* Native CSS tags */
.highlight .nt {
    color: #eb3beb;
    background-color: transparent;
}

/* CSS classes */
.highlight .nc {
    color: #eb3beb;
    background-color: transparent;
}

You can find the up-to-date stylesheet for syntax highlighting used on this website here.

For some more information on how to use block syntax highlighting in Jekyll, you can consult the official documentation.

Block syntax highlighting problems

Indentation of highlighted block

When block highlighting any snippet containing curly brackets, the {% raw %} command is needed in addition to the {% highlight language %} command.

However, this makes it so that Jekyll interprets the section of the HTML-file between the {% raw %} and {% endraw %} commands as is, including any indentation or whitespace.

If one does not pay mind to that, code blocks can end up looking all sorts of wonky, see the example below.

    /* Attribute name style */
                .highlight .nl {
                        color: #eed115;
                        background-color: transparent;
    }

So, make sure to disregard any file-level indentation (e.g.: indentation of HTML tags) when attempting to highlight a code block, if you want the beginning of the indentation of this block to be aligned to the left.

Overlapping lines (spans)

Initially I have also had problems with the spans containing each token to highlight overlapping, as can be observed below.

.highlighty .nl {
    dypglopggy: fooo;
    background-color: transparent;
}

To fix this issue, a margin can be applied, however for the margin to have an effect, the span needs to be set to display: inline-block; first. This yields to the following solution.

#post figure.highlight span {
    display: inline-block;
    margin: .15rem 0 .15rem 0;
}

Code block overflowing on mobile

Another problem was that the code block would overflow, off the righthand side of the screen, on mobile devices. This is happening because the browser cannot automatically insert line breaks wherever needed due to the {% raw %} command that is used inside code blocks.

However, this can be fixed by specifying a width for the highlighted code blocks, which are figures and specifying the overflow behaviour to scroll. Make sure to only set the overflow behaviour to scroll for mobile devices, to avoid unwanted side effects.

#post figure.highlight {
    width: 90%;
}

/* mobile */
@media only screen and (max-width: 869px) {
    #post figure.highlight {
        overflow-x: scroll;
    }
}

Conclusion

Though setting up syntax highlighting with Jekyll is rather simple, there are some bugs one could run into. If you decide to set up syntax highlighting in you Jekyll blog you are now well equipped to do so and know how to fix with some common problems.

If you enjoyed this article or found it helpful, you might want to check out my other articles and take a look at the next article in this blog series: "Refactoring my personal website Part 3: Share via social icons".