Labarum

Labarum: All the colors in the theme

I just pushed a point release of the theme to GitHub. The majority of the changes are related to colors and line adjustments based off of reading 12 Modern CSS One-Line Upgrades by Stephanie Eckles.

Crossing the line

Years ago, I read an article stating that although it’s good to underline links, it can be difficult in some circumstance because certain characters like q, j, p will touch the line. Some developers used box-shadow get around this and I had taken that route for this theme.

When I read Stephanie’s article, I came across a section I learned about text-underline-offset. I also checked that I can use it in most browsers before I let myself get excited. I spent the last couple of days refactoring my CSS to use this finally posted it.

There are still instances where the text intersects the line, but during writing this post, I came across this article on styling with underlines by Ollie Williams. In it, he mentions that the property text-decoration-skip-ink is on by default.

Well, I’m hoping that this understanding of how these things work lead to a better site in the future. Although, I still use box-shadow as a makeshift highlight for hovering over links, removing it from link underlining reduces complexity.

The space between us

Other than that, I’m doing some adjustments to line-height. Elements such as ruby, rt, sub, and sup can cause the linespacing not to be uniform within a paragraph. I adjusted the spacing by doing this in the root element but I do not like the way that it added space between all the other block elements on the page.

I pushed this change but it’s probably moving to the top of the list of priorities after I do some more research on the rhythm of line spacing.

Another coat of paint

I’ve decided to change the color for the headings so that it is closer to the basic font. This will increase the contrast ratio and make it easier to read.

For this, I learned to let go of trying to make everything pop out at you and let my readers enjoy reading the site.

The ReadMe

When I do a point release, I update the README.md on the GitHub project page.

Here are the release notes for this point release.

  • Improve h* tags by changing color to --text-alt
  • Make changes to text-decoration inspired by 12 Modern CSS One-Line Upgrades to various elements
  • Turn on debugging by default temporarily
  • Modify cursor on <abbr>
  • Adjust line-height to make sub, sup, and ruby elements less obtrusive
  • Add accent-color to root of CSS

As always, feel free to contact me if you have any questions or comments!

Categories:

Labarum: Can I has Cheeseburger and Debugging

A magnifying glass on top of a lady bug
"Scan System" by Mohamed Hassan.

In my last post about the labarum theme, I ranted about how I wasn’t going to re-invent the wheel. In this post, I’ll be talking about how I made some minor tweaks and decided to update the version to 1.3!

This post is mostly a “why did I do this” versus a “how did I do it”.

On the Edge of obscure

When I first started working with static site generators, I used a tool called Pelican. The site is still up at https://mandaris.github.io, but I had messed up the layout in the last couple of commits and haven’t gone back to fix.

I have a tendency to focus on details that don’t really matter to 90% of most readers and (I’m assuming) most writers of HTML.

If you were to look at a list of personal blogs, I doubt that you’d find more than a handful that use esoteric tags such as <dt> or <rt>.

I continued this trend with this release by adding some tweaks to <ins>, <del>, and <s>.

At this point, the changes are direct by me loading the page up and making adjustments in the browsers inspector.

Part of the reason that I keep looking into this is that goldmark/commonmark define strikethrough as a delete in the resultant HTML.

Obscure Examples

Here are some example paragraphs with the styling mentioned above.

This is a paragraph with deleted text.

This is a paragraph with inserted text.

This is a paragraph with strikethrough.

And just for giggles here is a ruby(ruby) example.

Toggling Debug

Early on in this project, I enabled some debugging from Hugo. It was really useful when making the theme, and hidden by default.

As the template has become more stable, I want to reduce the amount of text that is being sent over. Yes, I know that text is almost negligible but why generate it if I’m not using it.

As a user, you don’t need to do anything. Generating the debug output is optional and toggled off by default.

Labarum Plugin Settings for version 1.3

I’ve added the following to the plugin.json file to make it an option.

"field": "params.themeDebug",
"label": "Generate the debug information",
"type": "boolean"

And then I have if statement in front of the corresponding debug code

{{ if .Params.themeDebug }}

Can I has?

This is the most exciting part of this release for me!

During the discussion of implementing the table of contents, I had written that I about using has but couldn’t because it wasn’t supported in Firefox.

Well, the feature is now available to anyone using version 121 or newer of Firefox and other popular browsers1!

This came at a great time as I wanted to better integrate the plugins that Micro.blog offers. I wrote about the plugins late last year. That solution seemed to work for a while, but the <div> would sometimes render when it was empty. I was counting on Hugo’s handling of whitespace to remove any spaces and thus making the browser skip over rendering it.

I created a class in my CSS that would default to hiding things.

.optional {
  display: hidden;
}

I then follow this directly with code that makes it a block element if it has certain elements in it.

.optional:has(a, p, img) {
  display: block;
  margin-top: 1rem;
  padding: 5px;
}

After that, I added the optional class to the <div>in _default/single.html that contains plugins.

<div class="[ style-box ] [ optional ] [ text-center ]">

Next steps?

I don’t know.

Seriously.

I could add some styling to the optional components. Some of the other themes make those components look really good and was tempted to use something similar.

But, I don’t have the energy anymore and I want to focus on my writing. In fact, this release was mostly done a while ago and I’ve just been waiting to write up the changes.

If you have anything that you’d like to comment on, please feel free to email me at info@MandarisMoore.com.


  1. Sorry, no luck to those using Internet Explorer. ↩︎

Categories:

Labarum: Do Not Reinvent the Wheel

I’ve been working on this theme for a while. Marking things off and adding things to a list in my head of different things that I want to do in order to scratch my own itch.

The truth of the matter is that I may never be done done with this. There are edge cases that I can envision, those that I never thought of, and those that are so minute that it’s not worth putting the effort into.

With that being said, I can’t do everything.

In fact, I should not do everything.

Case in point, I was looking into getting my mastodon account verified and I was attempting to pull the host and username from the metadata that Micro.blog provides.

Otávio created a plugin [GitHub Repo] that references $.Params.mastodon.hostname but this is only available on the post level. I’d like it in the head so that I can get associated accounts validated and for other tools like browser extensions.

I sent an email to @manton and he verified this behavior. I put some code into the theme and it will eventually work without users having to do anything more.

But, what can I do until then?

I thought about making my own plugin that a user can put in the values for hostname and username. I could make my own separate branch of the theme that would have this hard coded. Since I’m working on this, maybe I could also add a separate piece to add more control over avatars and images.

I could … I could … I could …

No.

I know that I’m not the only one who feels that they could implement things to make things better. But, this isn’t my specialty. This is a fun project.

I quick search of plugins and I found the Meta tags plugin [GitHub Repo] by Manton.

I put the snippet that I wanted in and boom!

Problem solved.

The lesson?

I, you, and everyone out there don’t need to make everything.

Don’t let your perfect vision of what things are supposed to be stop you. Use the time that you have now to make and do something else.

Happy Holidays.

Categories:

Labarum: Optionals

A small but pretty cool v1.2.18 of Labarum. This will allow the Reply by email for Micro.blog, Reply on Mastodon, and Conversation on Micro.blog plugins to look like they belong on the page.

Single post with links to reply via email, Micro.blog, or Mastodon.

The next step will be to add a little more padding to the <div> that contains the links and to get the embed for the Tinylytics-for-Micro.blog plug to work correctly as well.

How does labarum add optionals?

There are truly great web designers here on Micro.blog and one of them is Matt Langford. He’s got a wonderful theme called Tiny Theme.

In it, he has different logic to test whether a certain plugin is installed and then perform logic for it.

{{ if templates.Exists "partials/reply-by-email.html" }}
  <li>{{ partial "reply-by-email.html" . }}</li>
{{ end }}

With labarum, I place these all in one <div> and hope that the underlying plugin doesn’t decide to add multiple lines some day in the future.

I’m using the browsers nature of not rendering the empty block elements.

What about tinylytics for labarum?

I ran into an issue when I attempted to add the tinylytics plugin for Micro.blog to the theme like the other plugins. Most likely a user error on my end caused by a conflict between when I initially added tinylytics and this plugin.

I didn’t want to have this update halted while I attempted to fix this.

As always, feel free to contact me with any and all feedback.

Categories:

Labarum: Header Links

The other day, I wrote a micropost about how I was deliberating on <a><h1>...</h1></a> versus <h1><a>...</a></h1>. I joked and said that I was only thinking about it for 59 seconds and as you are reading this post it has been a lot more than that.

Strictly HTML 4 speaking, headers are block elements and anchors are inline elements. But, in practice, I’ve seen anchors around headers in links and images for just as long.

But which one do I want to use?

I decided that I would do some experiments in my test environment and saw that the touch targets would be just a little larger if I switch the anchor to be outside of the header. Unfortunately, this would also mean that I would have to do a minor rewrite of the CSS.

Showing the initial state of links and headers
The previous iterations of the theme had already made a rule for this.

Another question that I had is what is more accessible?. I didn’t want to put effort into this if it meant that it would be a problem for people. So I enabled voiceover and navigated the page using the keyboard to get a sense of what it would sound like.

After listening to the two different versions, I created two rules to match up with what I had previously. I ran into a small snag as header is a block element that spans the width of the container.

Labarum links headers snag
I considered leaving it like this.

I then set width: fit-content to make it fit. As a draw back the box-shadow that I was using to underline the link only shows up on the last line and make long titles look a little weird to me. I considered added a span within the header but that feels like too much work.

Categories:

Labarum: A small comment

I updated the styling of comments individual posts. I actually rolled this out while ago but haven’t written about it yet.

Background history (feel free to skip)

Every once in a while, I get a response to one of my posts on Micro.blog. The Micro.blog service manages the comments for me and allows me to include them by adding conversation.js to the theme.

The first iterations of the Labarum theme would have the comments of a post show up on the index page. This was nice when I had a couple comments, but I had a few posts that had a dozen replies as part of a conversation.

I decided that if I have new people coming to an index or category list, they would be better served to see what I’m writing about first and then see the comments when they are looking at the individual post.

I moved the comments to load in single.html and was ok with them being indented a little bit to denote that they were comments.

Showing comments having additional margin compared to articles, headers, and footers.

You can find an example of a post with a reply in this post about how I lost my journal.

Promoting the comments

After living with the change for a couple of months, I’ve changed my mind about this design and want the comments to stand out as much as the article. The first step was to change margin to margin-top in the CSS rule for the comment.

The conversation.js places the structure like the following into the final rendering of the webpage

<div class="microblog_conversation">
	<div class="microblog_post">
		<div class="microblog_user">
			<img class="microblog_avatar" src="https://avatars.micro.blog/avatars/Number/Number.jpg" width="20" height="20" style="max-width: 20px;">
			<span class="microblog_fullname">Some User</span>		
		</div>
		<div class="microblog_text">
			<p> Some Text </p>
		</div>
		<div class="microblog_time">
			<a href="https://micro.blog/UserName/UniqueIDNumber">Date</a>
		</div>
	</div>
</div>

The name and numbers have been changed to protect the guilty.

Next, we have to add more styling for the avatar picture. It’s hardcoded to be 20 with no units and a max-width but thankfully, it has a class that we can add rules to.

.microblog_avatar {
/*     border-radius: .5rem; */
}

I had a stub for this in the style.css but only had a comment there for future/present me to fix. Thanks for nothing past me. I then did a search and past me actually defined this rule twice!

.microblog_avatar {
	display: inline;
	margin-left: inherit;
}

I’m letting you, the reader, know this because I’m going to invest some time into learning how to clean up the CSS and to show that pobody’s nerfect.

The last comment of this post

After identifying the different components, I played around with the idea of making it looks similar to the way I have the author information at the end of the page. I decided not to at this point in time to focus on the some of the other aspects of the site.

Categories:

Labarum: Ruling the horizon

A screen shot with numbers pointing to various issues with horizontal rules.
Two problems with the horizontal rule

I’m at the point where I’m looking at contrived examples and edge cases where my theme has issues. I don’t write like this but there might be someone who does. In the above picture, I see to problems the first is that the horizontal rule doesn’t really match up with the colors of the site. The second more egregious is that the line is ducking underneath the image.

I used the Inspect feature of the browser to check out what was determining the behavior of the line and saw that the ducking was caused by setting overflow: visible in the normalize.css. This isn’t the first time that I’ve run into an issue with something like this. As the browsers move closer and closer to interoperability, I’ve been questioning whether having normalize.css as part of the theme is important.

Ultimately, I decided to add the following css rule to fix the issues and will have to reevaluate later.

hr {
  color: var(--accent);
  overflow: auto;
} 

Feeding the Robots

I’ve been reevaluating the meta tags I had defined in a previous post. I was happy that it passes the validation tests but I’ve been thinking about how I share my writing.

Original, I truncated the description fields because I read that it’s better for SEO. But why? Search is results are getting worse and worse. It’s ultimately up to whatever social network to take the information and display it. Going forward, I am using the .Summary for the description.

I also added a property that allows you to set your mastodon username if you’re using something other than micro.blog.

I tested putting all the meta comments into one line to reduce repetition as in the following.

<meta property="og:title" itemprop="name" 
  content="MicroPost - &#123;&#123; .Site.Title}}" />

Unfortunately, the W3 validator marks it as invalid. I switch it to having multiple lines that use the same content. I thought about contacting the people who set the criteria for the test, but decided not to at this time.

Categories:

Labarum Final Final Copy 02 Final

Tuesday, I released a post with and version bump of Labarum. I then went on and recorded a podcast stating that theme was now “feature complete”.

Well, I was wrong.

I went to the Homebrew Website Club to do some socializing and shared my site with the others. I pride myself on having a site that is pretty accessible. Turns out that the color contrast on my links isn’t good enough. I knew I had tested the basic font, but had misattributed the links not passing the contrast test as an issue with the test itself.

Principal Skinner thinks the children  are wrong

Definitely, I needed an intervention.

So, I spent about an hour going through all the accessibility issues and HTML validation errors. Some of them I can’t change at this time because the code is generated by Hugo/Goldmark. For example, if you have multiple articles on a page (index or list) and they each have a set of footnotes or use a table of contents, you will get an error about them using the same ids for those items.

I’m not going to put the time or energy into that.

Other issues such as a warning about using a trailing slash in the HTML did make me pause for a moment. For example the following from site-head.html:

<meta name="viewport" content="width=device-width, initial-scale=1" />

And

<img 
  src="https://cdn.uploads.micro.blog/661/2023/children-who-are-wrong.jpg" 
  alt="Principal Skinner thinks the children  are wrong"
  title="Self Reflection can be hard."/>

I decided to keep examples like these and ignore the issue for now.

Other accessible issues that I’m not going to put more energy into at this point are the code blocks. Some of the contrast colors for keywords were flagged, and the tabindex="0" can make keyboard navigation more difficult than it needs to be.

The most egregious issue is that I use the colors in the headers and links at the very top of the page. I’ve since changed it in both light and dark mode to be something closer to the basic font color but still within the Nord color scheme.

Since I’m changing the colors, I’ll have to redo the images that I have in the README.md which will probably make me think of other things to change. I’m both dreading and excited by doing that as I’ve learned more about what makes for a good demonstration of Labarum.

What is the next opportunity for Labarum?

My favorite part about this post and this point release is that I’m writing about what I’m not going to do.

Sure, there are places that the theme needs improvement1, but I have never been more confident and happy with where it is. I looked at the git history and the first commit was February 21st, 2022. That’s a significant amount of time.

I want to spend more time putting stuff on the blog and less time on what it looks like.

There are going to be changes in the future.

But at this point, it will be focused on changes that are related to the content that I’m creating.


  1. I will not mention them in this post. As always, I’ll make note of any imput. ↩︎

Categories:

Labarum: A Mermaid's Tale

Mermaid daddy

One of the changes that version .117 of Hugo that has been allowed onto Micro.blog is the ability to use diagrams in your markdown. The documentation on diagrams highlights two different kinds of diagrams that you can include; GoAT and Mermaid.

When you make a diagram using GoAT, Hugo translates this into a SVG on the server side and then delivers it with the HTML for that particular post. You can find some really complicated examples of them on the GitHub page for GoAT and I’ve included one below to demonstrate.

P S I R T N O A P C R U E T T S S E N D A C P H R O O I C C E E S S B C P O R M O X P C L E E S X S P R E P A R A T I O N X

Mermaid is a diagramming and charting tool that uses javascript and will load different libraries as needed to create the final product. I believe that it can be used to make static deliverables that you could save, but -according to my understanding- that’s a separate module and outside what Micro.blog and most installations require.

In addition, Hugo does not include the connections to Mermaid, and it’s up to the theme developers to make sure this works.

When you get it working, you can have diagrams like the one below.

sequenceDiagram
    participant Alice
    participant Bob
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts 
prevail! John-->>Alice: Great! John->>Bob: How about you? Bob-->>John: Jolly good!

The Mystery of the Mermaid

I had to ask myself why am I putting the time into getting this feature working in my theme. At first glance, the goals of accessibility and speed do not seem to align with adding diagrams built with third party JavaScript framework. I’ve run this site for years and have used tools to create static images that I serve with alt text to illustrate my point.

Ultimately, it’s because I love DIAGRAMS!

I like being able to have a picture that goes with my posts. I don’t feel that I will be using a lot of these, but I want to help those who do.

And with all of my labarum posts, feel free to take what you want to make your themes better.

Splashing around with the Mermaid

I want to start off this section by stating that a lot of what I’m going to write about is duplication of the documentation found online. This is me documenting my process of applying it and my thought process at the time.

My first stop on implementing this is to open up a browser window to duckduckgo and then opening the first 3-5 search results of Hugo mermaid diagram from DuckDuckGo before reading the Hugo Mermaid documentation. I do this to get a feel of what developer roadblocks and experiences that I can note before reading the documentation. It’s similar to where I would read the discussion questions the teacher gives for assigned reading back in school.

The step of creating the layouts/_default/_markup/render-codeblock-mermaid.html is straight forward1.

<pre class="mermaid">
{{ .Inner | safeHTML }}
</pre>
{{ .Page.Store.Set "hasMermaid" true }}

The first line will go to the resultant HTML, and mermaid will look for items that have the mermaid class to get instructions on what kind of image needs to create.

The second line passes whatever was in the code block. This is typically the definition of the diagram but if you are more familiar or more adventurous you can pass mermaid directives or configurations as well.

The next step is to add something similar to the template.

{{ if .Page.Store.Get "hasMermaid" }}
  <script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs'; 
  mermaid.initialize({ startOnLoad: true });
  </script>
{{ end }}

I wasn’t sure why this needed to go on the actual page versus on the footer that would be used on every single page of the website. Most of the examples that I looked at had it on the single.html and this worked for individual pages but not for the index.html.

I placed it in article_footer.html until I get a deeper understanding of how Hugo wants to manage a flag that would toggle the loading of JavaScript.

Luckily, the browsers that I tested with only load the JavaScript once. I’m not a JavaScript expert, but I think multiple loads of the 7k line file might be frowned upon.

Colors of the Mermaid

After I got it working for the index and standalone pages, I tested the diagram with the dark mode of the theme. Unfortunately, the default text color does not work in all situations.

I checked the documentation on theming the diagrams and saw that I can change the theme by giving it as a parameter during the initialization of mermaid.

mermaid.initialize( { startOnLoad: true, theme: 'dark' });

This allows for the diagrams to look good in dark mode.

Dark diagram no background but in dark mode

This looked good in dark mode but not light mode.

Dark diagram no background lightmode

I then experimented with changing the background for div.mermaid and then having the diagrams render using the default theme for both light and dark mode.

Light diagram on light background while in dark mode

Good but not ultimately it just didn’t look good enough. I showed it to my wife and some people in a discord and they agreed as well.

I needed to find a way to make it toggle from default and dark.

Searching for the Key

Luckily, when I did my first third group of searches, I came across a Hugo forum thread on the “Correct way to embed Mermaid.JS2. And it had a link to this article to add Mermaid to Hugo with Dark Mode which is very informative.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{{- if .Page.Store.Get "hasMermaid" }}
<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs';
  let isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
  let mermaidTheme = (isDark) ? 'dark' : 'default';
  let mermaidConfig = {
    theme: mermaidTheme,
    startOnLoad: true }
  mermaid.initialize(mermaidConfig);
</script>
{{ end }}

On line 4, we set a property based on the weather the browser is in dark mode.

Line 5 is a ternary statement that chooses between the dark or default themes.

Line 6 is the beginning of a JavaScript Object. I feel that the way it’s in the theme will make it easier to maintain and extend in the future.

It’s all about that base

Mermaid does have a base theme that allows for you to define the colors for the diagram. Yes, I could have taken the time to learn how to pull colors from the theme or use the toggle from light and dark mode to set the diagram colors. But, that could be a long process to customize something that I may not use.

If you want to take this theme and approach, please do, and please have no hesitation to send me a link of your endeavors.

Limitations

Although this implementation does consider if the user is in light or dark mode, it does not switch dynamically. If you are on a system that changes the theme depending on time, you will have to reload to get the different theme. There are themes and walk throughs that show how to do this, but I feel that this iteration and my skill level are not at the appropriate level to implement it now.

Another limitation is that the diagram definition might find it’s way into the .Summary for the individual post.

Mermaid Treasure

Thank you for getting this far into my post. Here are some resources if you want to know more about Mermaid.js.

Accessibility Options
If you took the time to make the diagram, take a little more time to allow other people to get something from it.
Tutorials
Lots of examples on how to make diagrams
Live Editor
A quick way to make and test your diagrams before putting them in your posts.

What’s next for Labarum?

I need to do an accessibility and validation audit of the theme. I’ve been making some adjustments and haven’t been testing to make sure that the site is as accessible as I had originally intended.


  1. I’ve found other templates that will have this call a short code that takes a set of parameters that control alignment and zoom of the diagram. I have no plans on duplicating that kind of functionality at this time. ↩︎

  2. There is no One way to do this. ↩︎

Categories:

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 Micro.blog. 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 micro.blog 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 https://www.apstylebook.com/)
// - "Chicago" (see https://www.chicagomanualofstyle.org/home.html)
//
// 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)
  default:
    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">
    213
  </span>
</span>

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">
      213
    </a>
  </span>
</span>

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.

199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
// GetTitleFunc returns a func that can be used to transform a string to
// title case.
//
// The supported styles are
//
// - "Go" (strings.Title)
// - "AP" (see https://www.apstylebook.com/)
// - "Chicago" (see https://www.chicagomanualofstyle.org/home.html)
//
// 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)
  default:
    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 Micro.blog. 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 Micro.blog 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 }}
</aside>

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;
  float:right;
  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 Micro.blog about abstracting some of the code that is used in all Micro.blog themes. The discussion and pull request was on github and it can now be seen in the micro.blog 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 Micro.blog 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:

An IndieWeb Webring 🕸💍