Labarum: Code Blocks & Turning Tables

Turn Tables | by Peter Alfred Hess

"Turn Tables" by Peter Alfred Hess is licensed under CC BY 2.0.

I’m rolling out another update to my theme for It took a lot of time and effort on my part. It definitely reminds me of the story about how people paint both the front and back of a fence. I don’t think most will know or use some of the things that I put into this. If you do use or learn anything from this, I would really appreciate you sending me a message.

I’ve been doing small tweaks to the theme for the last couple of weeks as I learn more and more about CSS. I had even posted about how I had started working through the material found in Kevin Powell’s Conquering Responsive Layouts course and got a couple of responses that pointed me to further research.

There are plenty of miscellaneous changes that I put in related to accessibility and edge cases for HTML elements.

Back on the (code) block

I’ve been working on code blocks for a while. I don’t think there are many blogs on that feature code as a regular part of what they publish. It’s very important to me that as someone who is writing about the code of the theme that it can be read.

It haunts me.

I was ok with the fact that the code blocks worked well with Hugo version .91 but, with the availability of .177, I couldn’t ignore the problems that I saw.

Here is a picture of what I’m referring to from my post celebrating the announcement.

Code blocks in newer version of hugo

The underlining issue is that the default properties for the theme and Hugo is to place the styling inline of the HTML. AND, that I’ve opted to use display: inline-block for the <div> that is the container for my blog posts.

To better explain the issue, I’ll use the following snippet found in the Hugo documentation about code fences and put it in one of my posts, I’d get different results based on the version of Hugo that I’m running.

```go {linenos=table,hl_lines=[1,11,"15-16"],linenostart=199, anchorlinenos=true, lineanchors=small }
// GetTitleFunc returns a func that can be used to transform a string to
// title case.
// The supported styles are
// - "Go" (strings.Title)
// - "AP" (see
// - "Chicago" (see
// If an unknown or empty style is provided, AP style is what you get.
func GetTitleFunc(style string) func(s string) string {
  switch strings.ToLower(style) {
  case "go":
    return strings.Title
  case "chicago":
    return transform.NewTitleConverter(transform.ChicagoStyle)
    return transform.NewTitleConverter(transform.APStyle)

Hugo will render this as a series of nested spans in a table in a couple of divs. For example, the span that contains the line number would be div.highlight > div > table > tr > td:first-of-type > pre > code > span.

Hugo highlight div

Each level of this structure may have its own inline styling.

Going back to the code snippet, with version .91, I would get the following output for the highlighted line 213 (the one that with ‘case “go”’). I changed the spacing for legibility.

<span style="display:block;width:100%;background-color:#3c3d38">
  <span style="margin-right:0.4em;padding:0 0.4em 0 0.4em;color:#7f7f7f">

With version .117, you would get the following output for the same line.

<span style="background-color:#3c3d38">
  <span style="white-space:pre;-webkit-user-select:none;user-select:none;margin-right:0.4em;padding:0 0.4em 0 0.4em;color:#7f7f7f" id="big-213">
    <a style="outline:none;text-decoration:none;color:inherit" href="#big-213">

Note that this version allows use to set anchors for the individual lines as well as a prefix.

At this point, I realized that I needed to have a better way of controlling the behavior of the different elements. Luckily, the documentation for Hugo Highlighting configuration has a noClasses flag that we can set in the config.json of the theme.

    "params": {
        "showTableOfContents": false,
        "showAuthorInfo": false,
        "showDebugInfo": false
    "markup": {
    	"highlight": {
    		"noClasses": false

With the noClasses set to false1, the line that we’ve been looking at gets rendered to something like below.

Hugo highlighting code without any color or highlights.

The example is legible without the color and inline formatting.

To put the color back into the example, we refer to the documentation on how to generate syntax highlighter CSS to get the colors. I used the example that they provided so that I could compare it to the defaults.

hugo gen chromastyles --style=monokai > syntax.css

Then we add the newly created css file to our site-head.html to represent that syntax color is important but that the style.css is the final say for customization from the theme.

Unfortunately, the lines to do not … um… line up and the colors don’t match up with what we’re expecting.

Hugo highlight with color
Highlights not lining up for code blocks

After some experimenting with Firefox developer tools, I added the following to the style.css to get the lines to match.

.chroma {
  overflow-x: auto;

.chroma .lnt {
  display: flex;

.chroma .hl {
  display: flex;

The color for the highlight appears to be incorrect for all the styles that I tested, so I went back to an earlier version of Hugo to get the color and then placed it in the style.css as well.

.chroma .hl {
    background-color: #3c3d38;
    display: flex;

I also created a bug report about Chroma styles for line highlighting are not using the correct color.

As the last step, we remove the box-shadow from the links in the table.

.lnlinks, .lnlinks:hover {
    box-shadow: none;

The results of the highlight experiments

So the following is what the code looks like afterward.

// GetTitleFunc returns a func that can be used to transform a string to
// title case.
// The supported styles are
// - "Go" (strings.Title)
// - "AP" (see
// - "Chicago" (see
// If an unknown or empty style is provided, AP style is what you get.
func GetTitleFunc(style string) func(s string) string {
  switch strings.ToLower(style) {
  case "go":
    return strings.Title
  case "chicago":
    return transform.NewTitleConverter(transform.ChicagoStyle)
    return transform.NewTitleConverter(transform.APStyle)

You can also link directly to lines (for example, line 213) and it should work. It also scrolls side to side to accommodate the longer lines.

Showing the table of contents

Table of contents diagram

When I get frustrated with code blocks, I look at other aspects of the theme and what’s available in Hugo and Hugo offers built in table of content short code that can be used in the themes. You can read more about it in the online documentation.

My first idea was that I wanted to have a property that users could turn on to automatically add the table of contents to a post. I came across this feature in the Cards Theme for and thought that it would be a nice feature for those who write a long post.

I create _partial\toc.html with the following code that I would put above the <div> that that contains the contents of an individual post.

<aside class="[ TableOfContents ] [ style-box-alt ]">
  <h2 class="[ TableOfContentsHeader ] [ text-center ]">Table of Contents</h2>
  {{ .Page.TableOfContents }}

This would render as an empty box if there were no headers in a post. After a lot of experimenting, I came up with the following.

.TableOfContents {
  display: none;
  margin: 0 auto;
  width: 90%;

.TableOfContents:has(ul) {
  display: block;
  margin-left: 1em;
  margin-right: 1em;
  margin-bottom: 1em;
  padding-right: 1em;

Line 2 makes the default state of the table of contents hidden and then line 7 checks to see if Hugo has rendered a <ul> within whatever is in the .TableOfContents class. If it’s true, then line 8 will set the display type to a block; making it visible.

Problem Opportunity

Unfortunately, I ran into a number of issues.

  1. It does not take into account older posts that already have table of contents
    Most of my posts about labarum have headers and I do not want to go back and edit all of them. Some users might only want a table of contents that they specify themselves.
  2. It obscures posts that start off with a big “hero” image
    I have a couple of posts like this and the floating of the table of contents did not look correct. I will have to come back to this when I’m a little better with CSS.
  3. This technique does not currently work with Firefox
    The table of contents does not show up on Firefox. I tried experimenting with different logic to toggle the visibility, but ultimately, I couldn’t get it working. I don’t know how many people are using this theme or how many people come to my site using Firefox, but I really, really want people to be able to read this. NOTE: I wrote this on August 20th, and then the Firefox nightly build enabled the :has flag in build 119. Meaning that this will work soon.

I decided to remove the property and make two different shortcodes for table of contents.

The first one is activated by adding {{ toc }} to your text and will float in the center of the article.

Labarum table of contents changing from light mode to dark

The second one is activated by adding {{ floating-toc }} to your text and will float in the right of the article.

Labarum table of contents turning from light to dark mode

Please note that if you place the short codes at the beginning of the post, it will be part of the .summary.

A Standard Head

A while ago, Sven (@sod), mentioned a couple of people on about abstracting some of the code that is used in all themes. The discussion and pull request was on github and it can now be seen in the theme-blank.

You can test it out on your local environment by cloning it and placing it with the other themes.

After you’ve cloned the theme, you edit your config.json to something similar to what is below.

"theme": ["labarum", "theme-blank"]

I then edited the partial\site-head.html to have the following:

{{ "<!-- Microblog header begin-->" | safeHTML }}
{{ partial "microblog_head.html" . }}
{{ "<!-- Microblog header end -->" | safeHTML }}

Here is a direct link to the microblog_head.html partial if you want to read over it.

What’s next?

There were a couple of things that I wanted to add to this release but realized that I was stopping progress. In my last two posts about labarum, I told myself that I wouldn’t wait for perfection to happen.

That being said, here are the things that I have on the roadmap for my next release.

Show the Profile Picture

A couple of the other themes on use the profile picture on the site. I do load this picture in the metadata of the theme’s head and articles but an end user doesn’t see that. Part of this is just me not wanting to show my face and not having it in my initial design for the theme.

Enable Mermaid Diagrams

Hugo natively allows for GoAT diagrams2 which are rendereded as SVGs on the site. To enable mermaid, you have to place something in the theme. I’ll be experimenting with and hopefully find a way so that it doesn’t load the associated javascript library if a user doesn’t want to use it.

Reevaluate OpenGraph and other meta tags

There was a pull request and discussion about abstracting the metadata and placing it in “theme-blank”. I currently do this myself and wrote a post about my journey.

I’ll have to read more. I like the idea of having a standard, but I vaguely remember something about why I made the decisions that I did.

CSS responsiveness

Working with my theme makes me appreciate other web developers. Unfortunately, I start comparing my work to others, and comparison is the thief of joy. I’m not happy with a part of the theme that I have. It has to do with how it looks on smaller screens.

Labarum separate articles on small phone
The borders on the side complicate the image

Nothing is “wrong” with this, but for some reason, it “does not spark joy”.

I’ll have to take a couple steps back and think about what I want from this.

Break time!

Thank you for getting to the bottom of this article. I certainly hope that you got something out of it.

Please contact me if you have any positive comments or questions!

  1. I have a hard time following “not false” instead of “true”. ↩︎

  2. The name makes it harder than it needs to be to find examples. ↩︎

Categories: Labarum

New version of Hugo offered with

Added Hugo version 0.117 as an option on the Design page for your blog.

I've been seeing differences between my current home setup and what's on and always attributed it to some difference in my environment and what is on the server. Some kind of secret sauce.

Unfortunately, it looks like something changed in the way that Hugo (or maybe goldmark) handles code blocks.

Code blocks in newer version of hugo

I’ve got it running on my test blog and have a post that I can refer to so that I can tweak the CSS to go with this newer version.

Table and Gist

Still, I’m excited because this release has a lot of cool things since the v.91 that I’ve been targeting. Such as…

92 Removes depreciated .Page methods

Markdown diagrams and code block render hooks

20% reduction in build time and memory usage

Error handling release

Gif image processing

Updates to 404 support


Update to code highlighting

Change to the render hook so that you can have it make it so that stand alone images are placed in a

tag. When I look at my blog, I see that you have something there to handle this behavior.

You can checkout the release notes here:…

Categories: Labarum Microblog

Labarum: Code and Codeblocks

I really wanted to do more writing instead of working on labarum, but I found myself wanting to write more about it. The very first post had examples of code that would render outside of their container depending on how long the line of code was.

Labarum example codeblock
The code blocks would allow you to scroll along blocks that weren't formatted properly.

It drove me crazy and I would sometimes edit the post in order to avoid the problem.

It was an itch. An irritation.

I needed to fix this.

A cascading problem

Some of the other themes do not have a problem with code blocks at all.

The problems arise from my previous decision to allow for images to float along side content for a post and still remain within its container1.

An article contains an optional header followed by a div where the content is placed. Finally, a footer which contains information about the contents.
Diagram showing structure of an article.

This lead me to a small crisis of confidence. Am I putting too much effort into use cases that 99%of the people using the theme are never going to see? Am I essentially playing wack-a-mole trying to handle anything that is sent as content?

I don’t know what the future might hold as far as content, but I do know that most of the posts with titles that I - the theme creator- writes have some kind of code in them.

So that leads us into how do I fix this problem?

The Problem

The problem is actually multiple different scenarios.

  1. Code within a paragraph
  2. Code blocks
  3. Code blocks with a language tag
  4. Code blocks with a language tag and highlights

I decided that I would start at the bottom and work my way up because it looked to be the hardest problem. To test my work I made on my local system and placed a copy as a post my test blog. Feel free to use it to follow along at home. Please be aware that sometimes, the text processor makes the quotes “smart”2!

Code blocks with a language and highlights

This was hard for me to solve.

Hugo uses goldmark to process the markdown and then pygments to color things. The resulting export is essentially a table wrapped in a couple of divs.

I created this simplified diagram to illustrate my mental model.

A div with div with a table with two table items defined.
Sometimes automatically generated code can be complicated to read.

I did some additions to the .highlight class in my style.css in order to get it to fit. I created a value called --max-width-value that my <body> now uses and then set the .highlight to use the following.

overflow: auto;
max-width: calc( var(--max-width-value) - 2rem);

After that I noticed that the individual spans and divs weren’t working so I added the additional block below.

.highlight > div {
    width: fit-content;

Within the table, there is a <pre> and <code> tag that both have hardcoded values. I suspect that these are the defaults and could probably be changed in the config.json file, but I don’t know how to change them at this point in time. Maybe a later iteration.

For now, I set values in my css for the <pre> tag so that I don’t inadvertently change something in code.

Within that table, everything is styled by <span> tags. I don’t make any changes to those because I’m at the limit of my current knowledge.

Code blocks with a language tag

These are not placed in a table, but still use the .highlight class so I get most of the changes that I had put in for the previous scenario. The problem testing what would work for both.

Code blocks

This does not use the .highlight class. It does use a <pre> tag with some hardcode values. I added some padding on the top and sides to this example and should make more examples to test it out.

Code within a paragraph

I feel that <code> within a paragraph should probably stand out versus the code blocks on the page.

p > code, kbd {
	background-color: var(--background);
	color: var(--text-alt);
    padding: 3px;
    border-radius: 5px;

What is the next step

I’m going to continue tweaking the colors and rules a little bit more for code blocks. This post is actually another good example of how it is used. I would really like some feedback or better examples on how to work with this, but I think I’ll save any energy I have on finding a better font for this.


While working on this issue, I used the following tools.

Unminify CSS

There are couple examples that I would pull from that had a minified version of their css file. I used this to get a better read at what they were doing.


I was told about this tool so that I can reduce the file size for the images in this post.


I love making diagrams!

  1. See Floating Images section in my restarting iterations post here↩︎

  2. I am not a fan. ↩︎

Categories: Labarum

Labarum: Official 1.1.0 release

Showing the cycle of coding, writing article, finding an issue and then repeating.
One feeds into the other.

I did an “official” point release for the Labarum theme last night. I had previously been keeping the version number in the site-head.html and did not change the plugin.json file that would alert the different workflows that a change had actually happened.

What is new

In addition to the the changes in my last post, I added some margin to all images, figures, and videos on the site to better handle some of the content that is added from other sources than MarsEdit and Drafts.

Navigation links are in a raised box

I also used the same styling on the navigation links as I do the articles. This will make them more legible. For all of the talk about accessibility, I was using the contrast between the article background as a test and not the background that you normally see.

All your base

In my last post, I mentioned that I wasn’t using any plugins.

Turns out, because I wasn’t using them, I didn’t know that some of them weren’t working. In one case, the Search Space plugin by @sod.

After looking into it a bit more, it turns out that I had set the <base> element in my head for the theme. This causes all relative links to go to the base1 of the website. In this case, it made what should have been into As an added problem, footnotes would go to the main page of the site as well. I didn’t see it because I only looked at my articles on the main page and hadn’t looked at my older post in a while.

I found this really nice article about what use cases the <base> really shines.

Strangely enough, I’m actually a lot more confident in the quality of my theme after finding this issue.


This is a small little change that most will never see, but I’ve added some code to improve what is parsed when you use a webmention. Some of this is really dependent on what kind of client someone is using to parse the Webmention, but I feel that this follows the specs pretty well.

What’s the next step?

I’m going to continue to reevaluate the way that site looks to me. To paraphrase @pimoore, “theme design never ends, it goes on hiatus”.

I’ve identified the following things that could use some improvements.

  • Improving the way code and code blocks look. Code blocks look really, really and break out the article > div that they are in.
  • Change the responsiveness of the site in general. This is one of those “It works on my machine” situations. The margins of the site are all based off of an example that I found years ago that worked on my devices. I want to make sure that it’s “better” or at least not worry about it not being perfect2.
  • Refactor CSS. It’s getting harder for me to read what I put in there. I’ve been given a suggestion on how to organize it. I’ll probably tie this into the effort to change the responsiveness of the site.
  • Update the I want to quickly see all the things that this theme has to offer without having to browse my site or apply it to their own.

With all that said, I want to spend the next 20 to 30 days focusing on the content of the site more. I’ve put a lot of energy into how the theme works and I want to do more writing and podcasting. I found that I started comparing my theme to others and it was taking some of the fun out of it. If I focus on creating stuff, I can have a better understanding of where I want the theme to highlight the things I make.

So, feel free add it as a plugin on, browse the code on Github, or contact me via how ever you got this article.

  1. In hindsight, I should have known and seen the problem earlier. ↩︎

  2. Perfection does not exist. ↩︎

Categories: Labarum

I was experimenting with webmentions a lot today. Still have a couple questions, but I think I’m done for the time being.

Webmentions processed on another person’s site.

Categories: Labarum Microblog

Labarum: Restarting Iterations

During my Micro Camp presentation, I stated that the first publication is the first iteration…

Then I stopped.

Just a lot of little things got in the way, and I started to sit on changes that I have made. I’m hoping that this post will be me getting back into publishing changes and why I am making them.

Here’s a list.

This whole post probably should have been run through a grammar checker, but I felt that if I did that I wouldn’t be able to finish it. I welcome feedback so that the next post is better!

Floating Images

Right before Micro Camp, I used MarsEdit to write a post and I used one of the built in alignments to float the image to the left. I was hoping that it would look the way I remember old newspaper articles being.

Image with text wrapped around the right side

Although it did have the text wrapped properly, the image “escaped” out of the article and onto the following article.

Images not showing up properly in theme.

This was at the same time that there was a discussion about floating images in the help. With this information, I created a little demo post to help me evaluate the preconfigured defaults in MarsEdit.

The way, I got to it was dragging an image onto a post to get to the Upload Utility, but you can also access it from the Window menu.

Upload Utility

From there, you can select the options in “Format” or click customize.

Options for formating media in MarsEdit.

Afterwards, you can add more styling to the markup of the image so that future post can use what you’ve been working on.

Modifying the format of posts.

This works for smaller images, but fell apart when I used a long image with small text. I went on a very long online journey look at grid and flex box until I ultimately, came to the following code that expanded the <div> that I use for the content of the post.

.post-body {
    display: inline-block;

Three lines and it only took me hours.

Handling Transcripts

I had some code that would check if the post has a transcript for a podcast associated with it. That’s been removed as automatically adds this for you. Thank you, @manton.

No Longer Published

Post stating when the  article was published.
I think people can figure out when this is released

When I first started working with the theme, I thought I would show the modified date and published date so that my users could quickly tell when something had been updated.

Looking at other themes, I don’t see many that have this information and it’s assumed that any date on the post is when it was published. I’m still keeping mine on the bottom for now. Although, I sometimes thinking about how a post might be more comparable to a journal entry or letter to the world.

Center Navigation Menu

Most of the other items on the page are centered. For example, the articles and footer. I centered this and gave it some margin.

Describe me

I’ve been using .Site.Params.description incorrectly. I’ll be using .Site.Params.itunes_description for the description used in the main page meta data.

No Comment

I moved comments from the posts off of the main page and out of the article block that they would normally be in. This meant moving the following code from the partials/article-footer.html to _default/single.html.

Thank you, @Miraz for helping me make up my mind.

What’s next?

I’m thinking about changes in two different areas.


The next step is to reevaluate the styles that I’m using for the site. I’ve been adding things as I’ve come across different use cases and I want to make sure that the css file while stands at 496 lines currently is easy to read and understand for Future Mandaris 3 months from now. My friend, Michael, told me about Cube CSS so I’ll be looking into using that as a way to organize it.

I’m not happy with the way that comments look. I’ve decided that I’ll only change the style after I’ve implemented Cube CSS otherwise I’ll only have spaghetti code for the rest of this project.

I’d also like to change the margin between images on the site. For example, this post that I made with the sunlit app. That might be a simple fix that I’d slip into a point release.

After that, I’m planning on making the <code> and code blocks look more seamless in posts and change the font such that they stick out more when reading in a paragraph.


On my site, I don’t use any of the plugins. They should work, but I’d like to make sure that the most popular (AKA the ones that people I follow have mentioned) are working properly.

I don’t see there being a problem because of the nature of the theme, but if you know of an issue, please let me know.

Categories: Labarum

Some thoughts on labarum designs for the future

A small post on my site

I’ve been thinking about where I want my theme to go next, and have been looking at other themes for inspiration. When I look at the other themes, I see that they usually have the time posted on the post but don’t have text stating that it’s the time that it was posted. There is the general assumption that it’s what the date is for.

In addition, some of them have the date before the posting.

I’ll have to sleep on it.

Categories: Labarum

Oh! Hey! You want to check out my theme and see how awesome it is!?

Images not showing up properly in theme.

Face palm.

Categories: Labarum

It's the little things in different browsers

Boxes in front of checkboxes
Labarum: Extra content in items
I hate it when a developer focuses so much on one browser (usually chrome) and doesn't test it in another browser. So, I feel like a hypocrit when I found out that my site renders the little box in front of the checkboxes[^checkboxes]. The funny thing is that I had originally seen this as an issue and had commented the code out.

The I thought I would keep it as a comment until I could figure it out and deploy it as a point update.

article ul > li::marker {
	/* content: "\2751"; */

The problem is that chrome doesn’t care that I had the individual line commented out and was attempting to put it there even though I told it not too.

I moved the comment to outside the item and I’ll let the broswer handle markers until I get a better understanding of how to target the different items.

Categories: Labarum

Creating Labarum (Part 6): A Splash of Color

Labarum part6 light mode

I’m wrapping up this series. I’ve been playing with this theme for more than a year. Rarely consistent and not always forward progress but rewarding. I’m at a point where I’m very happy with how the theme looks.

This is what it looks like in dark mode.

Labarum part6 dark mode


I wanted to use the Nord color scheme at the beginning of this project, but decided to use “basic” colors to simplify the design. I eventually grew to love the look of the page as the content was the star.

Later I found that some of the elements on the page don’t work well for those who are color blind and the starkness of having an all white background made me rethink whether the site would do well with long pieces.

I first came across the Nord color palette when I met Jessica Smith online using the service.


I did not want to use online fonts.

True, they can look really nice but I didn’t want to use bandwidth on something that could slow down the site or cannot guarantee to work in the coming years. In addition, there are privacy concerns when it comes to web fonts that I didn’t want to contribute to.

After a significant amount of time looking for accessible fonts that are all the major OSes, I went with Verdana for my main text font and Garamond for headers.


I decided that I wanted the items in a figure to take have the same effect as the articles but take the main background so that it would have a stacking effect.

Labarum figures light mode

Here are some pictures of what the figures looks like in dark mode.

Labarum figures dark mode


I typically don’t use tables in my writing, but I thought I should add a little bit of styling in case someone else feels the need.

Labarum table light mode

Here it is in and dark mode.

Labarum table dark mode

Tasks lists

This was the hardest part to solve because most of the Hugo themes do not address tasks lists. To be clear, these are static lists created by the writer and not something a reader is expected to interact with.

Labarum task list light mode

Dark mode for the task list.

Labarum table dark mode

Most themes will have something like the following code to remove the markers that show up in an unordered list.

/* task list and its checkboxes */
article ul > li:has(> input[type="checkbox"]) {
    list-style: none;
    margin-inline-start: -1rem;

article ul > li:has(> input[type="checkbox"])::before {
    content: "\200B"; /* accessibilty for Safari []( */

Eventually, I found a wonderful example in the Hugo Relearn theme that was written about on Modern CSS applied it to what I had.


I’m happy with the theme.

There are still somethings that I want to improve upon and I invite you all to comment and help me make it better in the future. I’ve also made a post on my test blog that should have a lot of examples of the theme in action.

Categories: Labarum