Syntax Higlighting Problems

The allure of nice syntax highlighting without leaving Markdown was one of the things that drew me to Hugo. In practice, I have found there are a number of challenges in implementation to get it to work as I expect. I was also reminded why I prefer not to spend my time fighting with CSS. ;)

A Helping Hand

Before I get into the meat of the post, I wanted to give a shout out to @the_mckern and the gist he shared with me. Without that, I would have spent even more time fighting with all of this.

As it is, I probably should have given up and spent the time elsewhere, but at least I was able to turn it into a post. ;)

Some Background

In my first post I covered installing Hugo with Pygments. In a later post, I talked about the migration from Pygments to Chroma and I referenced what appeared to be a styling bug in Chroma when using linenos=table.

Shortcodes vs Code Fences

Now I seem to have found another issue - a bit of extra padding that crept in during one of my upgrades of Hugo or my theme Beautiful Hugo. The following CSS seems to be causing the problem. The first is displayed with the highlight shortcode.

1
2
3

pre code.hljs {
  padding: 9.5px;
}

Compared to code fences:

1
2
3

pre code.hljs {
  padding: 9.5px;
}

And that code seems to come from an auto-generated /css/codeblock.css file with the following contents:

1
2
3
4
5
6
7
8
9

/* --- Code blocks --- */

.chroma .ln { 
  margin-right: 0.8em; 
  padding: 0 0.4em 0 0.4em; 
}
pre code.hljs {
  padding: 9.5px;
}

And from poking around this file comes from the Beautiful Hugo theme and can be found here. I wrote this finding up in a new issue.

Based on the help from @the_mckern, I decided to convert back to using Pygments instead of Chroma since I could get the code blocks looking more or less like I wanted. I’m sure I will come back to Chroma at some point but not until I’m willing to do the work of converting the table.highlighttable styling over to match what Chroma outputs.

Scrolling Challenges

I’m also seeing some scrolling issues.

Instead of scrolling horizontally, I was seeing longer lines lead to cutting off some of the spacing on the left-hand side of the line numbers (pulled from a previous post of mine). I resolved this by adding min-width: 2.5em; to the styling for table.highlighttable td.linenos.

Also the following two code blocks should be the same width as the ones above but aren’t (assuming I haven’t corrected the CSS by the time you read this). The first one should be ~10 characters longer than those above.

1
2
3
4
5
6
7

{{ if .Params.tags }}
  <span class="post-meta">
    {{ range .Params.tags }}
      #<a href="{{ $.Site.LanguagePrefix | absURL }}tags/{{ . | urlize }}/">{{ . }}</a>&nbsp;
    {{ end }}
  </span>
{{ end }}

If I make that line even longer it eventually wraps leading to the line numbering to be off.

1
2
3
4
5
6
7

{{ if .Params.tags }}
  <span class="post-meta">
    {{ range .Params.tags }}
      #<a href="{{ $.Site.LanguagePrefix | absURL }}tags/{{ . | urlize }}/">{{ . }}</a>&nbsp; longer and longer
    {{ end }}
  </span>
{{ end }}

In both cases, I would have preferred the text to force a horizontal scrollbar but otherwise stay within the horizontal spacing of the rest of the post.instead of scrolling as I would have preferred. This is the behavior I had seen in some original posts that made me think it would work well for posts that rely on being able to display especially wide content without wrapping - like my first Kubernetes post when displaying the result of sudo docker ps.

So far I don’t have a solution for this. For an example of what I was hoping for, take a look at the code block after “Example gist Output” on the Hugo shortcodes page. you should see a horizontal scrollbar indicating there is more text to see and when you hover the mouse over it the code block extends to the edge of the window.

Moving On For Now

I’m (hopefully) leaving this alone for now after I spin through and convert my previous posts to use code fences instead of shortcodes. I have other posts to write that I’m more excited about than this frustrating reminder that CSS and browser compatibility is hard and better left to experts (i.e. not me).