Short answer: no.

Too long answer: read the rest of the article.

Also, click here to get to the code portions of this article.

The popover api has been baselined and I really wanted to explore what this feature can do for me and my writing. I thought it would be a simple project of looking into what it is and how it could help me be a better communicator on the internet.

When it comes to using new methods, you are better served by having a target or project. It just so happened that I’ve been thinking about whether or not footnotes are a good solution to adding tangental information to my posts.

So far, I’ve spent 2-3 hours researching and talking about this before I even started writing this article. I lost track how much time it took to get images and tests.

What is the popover API?

To put it in my own words, the popover api allows you to define an element in HTML that will pop up and over the rest of the content. This element is initially hidden and then can be toggled to be visible and above the other elements.

Examples from the internet

I got a lot of this from different resources on the internet. Here are some links to tutorials and examples if you are interested.

Popover API lands in Baseline

Written by Una Kravets and she makes it very easy to understand the concept with a nice break down of what separates this from using a modal dialog.

Dialog dilemmas and modal mischief

Hidde De Vries has a slide deck with links to articles that he wrote about popover. I was planning on using some of his accessibility suggestions during the writing of this article.

MDN - Popover

Very nice documentation page. Don’t forget to check out the examples that they link to.

Does it work on my device?

Yes.

I’m currently using an iPhone SE running iOS 17.4. You should also double check the CanIUse website to see if it’s on your target device.

What’s wrong with footnotes?

I came across footnotes during my introduction to Markdown. I found it to be a great way to place add additional thoughts and information to something that I was writing without diverting too much from what I intended to say.

I still think about how a piece of writing might be improved with footnotes. I use it mostly for jokes and sarcasm at this point and attempt to write more comprehensive paragraphs with single ideas or wrap additional ideas in the current or following paragraph.

I’ve also thought about saving the ideas for footnotes to be a separate post altogether when I’m doing a daily writing challenge and start looking for ideas.

Footnotes still serve a purpose in how they display information and the various tools that have been developed to utilize them have made them easier to read and write.

But there are still a couple things that don’t really sit well with me.

Not quite a spec

Unfortunately, this isn’t something that was originally built into HTML. Most of the Markdown implementations denote footnotes as an extra feature. Although, all the implementations that I’ve used seem to have this on by default.

For example, Goldmark is the implementation that is used as part of Hugo and Micro.blog. It will go through a document and replace the reference to a footnote with a link like the following.

This is a cool idea<sup id="fnref:1">
<a href="#fn:1" 
  class="footnote-ref" 
  role="doc-noteref">1</a>
</sup>.

This works for single posts but navigation can be confused if there are several posts with different sets of footnotes or is the base attribute is defined in the head of your html causes the anchor to find the link on the URLs main page.

Accessibility is questionable

Years ago, I read this really cool article on accessible footnotes with CSS by Kitty Giraudel. I didn’t implement it at the time because I didn’t want to breach the imaginary threshold of having HTML mixed in with my markdown.

Still, I was curious on how these things get implemented. How does someone who is using a screen reader know that a link goes to a footnote?

When I started looking into it, I noticed that links were also getting assigned different roles. I thought that it was just a workaround.

Apparently, as I was writing this huge rant article, I found out that the role=doc-noteref has been added to the aria spec. It’s because of this that browsers and RSS readers can better parse an article to show a footnote without having to scroll to the content.

I didn’t do further research or testing with screen readers to get more information for this article after discovering this.

Do they work for me as a writer?

I use footnotes mostly for jokes and sarcasm at this point. But I want to be able to tell a story without them. In that effort, I’m attempting to write more comprehensive paragraphs with single ideas. When I process my pieces through a grammar checker, most of them state that my writing is at a high school level. Which I feel is probably the best target to get ideas across to others and not cry too much when I read this post a year from now.

I’ve also thought about saving the ideas for footnotes to be a separate post altogether when I’m doing a daily writing challenge and start looking for ideas. I don’t have too many of those as I do not allot dedicated time to writing and these idea fragments are then forgotten as the initial passion was spent during the writing and editing of the main piece.

To implement the popover for this theme, I felt I would need to break it down into several steps to get it working and see if it would be something that I would continue to use after putting the time into it.

Step 1: Review my writing process

With the first step, I thought it would be broken down into two smaller steps.

1. How am I currently writing on my blog?
2. Do I write in a way that including tangential content would make a piece better?

I currently use Micro.blog in order to host and distribute my blog. The service has an emphasis on making short posts that you can add images and more to. I like to think of it as one of the first successful twitter alternatives before there were so many that we see. This is generally where 90% of my writing goes and I feel free to post there without worrying a lot about editing.

Looking back, the longest posts are about Micro.blog. Some would joke that my Micro.blog posts are MacroPosts.

If I’m not using drafts or Marsedit, I’m using the application or shortcut to write for my site. I upload pictures of my dog or sending little messages about what is on my mind.

Because of this, I found that my average post length is about 45 words on average.

Very rarely do I find myself tackling multiple ideas in a post.

Step 2: Adding a popover to something that I’m writing

Adding a popover is pure html. I was tempted to create a Hugo shortcode into the theme, but I had a small discussion with Mathew and he pointed out that adding shortcodes could prevent users from changing theme. I could have made the shortcodes into a separate repository that people could use as a plugin, but I didn’t want to make something that would cause work for other theme creators to support.

Anything that I want to add by using this would need to be in the post that I write.

This means that I’m writing this as HTML in my document. For example, I’d write something like the following. Note that I added extra break points for legibility.

<p>A simple paragraph with a button
<button popovertarget="test-pop">+</button> 
in the middle of it. This is some more text just 
to pad this out a little bit more.</p>

I would have to add the popover content somewhere else in the post like the following.

<aside id="forth-popup" popover>
<p>Potential Footnote: 
  Some random text that I can place 
  in the middle of the sentence</p>
</aside>

One benefit of this approach is that I can add footnotes that are multiple paragraphs or images without worrying about having to indent the extra content the correct amount to make sure that it is included.

Step 2.5: Styling the popover

Although this is base line, I would like it to look like it fits into the rest of the theme.

I thought of the implementation as if it were a margin note or aside from the Tufte style of information visualization. This way, I can use the styling with my regular writing if I don’t want it to popout. I also used the nested css syntax to keep it all together.

After hacking away on this, I realized that it’s better to group everything together to be consistent.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

[popover],
.aside-info,
figure {
  background-color: var(--background);
  max-width: 90%;
  margin-left: auto;
  margin-right: auto;
  padding: 10px;
  border-radius: 5px;
  box-shadow: 0px 2px 7px var(--box-shadow-color-1),
    0px 7px 13px -3px var(--accent),
    inset 0px -3px 0px var(--box-shadow-color-3);
}

Line 1

This will effect all elements that have the popover attribute. It was nice to see that I could use this on <aside> and not just the <div> that I see with a lot of examples.

Line 2

I felt that I didn’t want to apply this to all <aside> tags that are in the theme. I don’t know how many users are adding that tag to their blogs and I didn’t want to make this something they needed to restyle.

The rest is the definition of the <figure> styling rules which have been implemented earlier in the project.

Do they work for me as a reader?

Sometimes, I actually test what I’m implementing. In this case, it is reading things on my blog.

Looking at it in the browser

At this point, I’m not used to having buttons in the middle of a paragraph. The combination of line height and where the button sits makes me feel that sentences are disjointed. There is no styling for the buttons and everything is inherited from the colors of the theme.

In an effort to get done, I felt that it would be better to ship this and write a check for Future Me to improve.

Oh, here’s a note from Future Me…

You're a lazy and handsome person! I both love and hate you! Future Me

Thank you?

Looking at it on my phone

I can see the popover show up and cover the contents. It can really highlight a point that I’m trying to make, but if I’m trying to make a point it should be within the writing itself.

Accessibility?

One of the good things about this is that this is keyboard accessible. You can dismiss the popover by clicking escape or tabbing and enabling another interactive element if the popover attribute is set to auto which is the default setting.

I am concerned about how I can make the buttons more accessible. I was thinking that I could add an aria-label to them if I continue to use this technique.

Final Test: NetNewsWire

I read my RSS feeds in NetNewsWire. You can’t see in the screenshot, but the buttons don’t work to show the content.

This gives me an impression that either the article or application is broken and should be skipped so that I can read some other feed.

I don’t have the time and resources to go about creating an enhancement in NetNewsWire for this and I do not feel that my usage justifies that someone implement this.

Conclusion

Popovers are not going to work for me at this point for use as footnotes.

In addition to some of the issues that I highlighted in this article, I’m not comfortable with having elements that I wrote that are not visible. Unlike xkcd, I don’t have hidden text as a bonus for the content.

One other issue that I ran into while testing is how posts show up in Micro.blog listing interface. I attribute this to the popover api being newly available and an edge case for this writing.

This was a fun exercise, but I think I’ll continue with using footnotes as they are currently implemented. Hopefully, the popup api is used for cool things before it becomes the thing we all disable it for forcing us to look at ads.

This release is mostly centered around cleaning up different edge cases in the theme. This the first time in several point releases where I’ve made a change to the HTML structure. The release before (V1.3.07) was an addition to the theme that we won’t be seeing on Micro.blog until we update Hugo. I feel a bit of accomplishment in the fact that I didn’t see a need to.

Here are all the changes from the README.md that I haven’t blogged about.

v1.3.08

• Adjust fonts
• Make the a.no-decoration more accessible by changing contrast
• Add FloatLeft css class
• Add ::selection background color to match up with theme
• Add scrolling for debug output
• Change the title and aria-label for microposts to include the date and time. In the local copy of Hugo, an empty string title is automatically added.
• Add styling to the top of the list.html to make it stand out.
• Change the date format for the time used for published times.
• Rearrange reply order options to be Micro.blog, Mastodon, and then email
• Add articleSection to list of classes for category tags on a post
• Update README.md on previous releases

v1.3.07

• Add partials for upcoming mathematics support in Hugo. This can be seen when you toggle the math parameter. This has been defaulted to false until v0.122 is available. Demos can be seen on the MathJax demo page.
• Use Modern Font Stacks. Matt Langford discussed this on the Tiny Theme page on fonts. I really liked his implementation and you should check it out!

v1.3.06

• Change the li marker color to --text-alt in order to match header color
• Change padding of body to utilize more space on smaller screens
• add text-shadow to a.no-decoration
• Change logic for the debug flags
• Create stub for theme example folder
• Temporarily add the rsvp shortcode to theme to remove extra whitespace when post is cross posted to mastodon

If you’ve come to my site, you’ve seen it. Or rather, seen that it isn’t there. Most site have them, whether it’s a big banner or image that lets you know that you are on a webpage. I’m referring to the header; usually the first h1 element in the html. Open any book on HTML and it’s one of the top five elements that you learn about.

But, if this element is so basic and used so often, then how why do I not use this in my theme?

No guarantee on structure

There are different tools that you can use to write posts for micro.blog. You can post from the website, MarsEdit, Ulysses, drafts, etc. These tools usually allow the end user to write in some form of Markdown syntax. If you look up the syntax for Markdown on Markdown Guide Basics Syntax or on the DaringFireball Markdown Basics page, you will see that the first thing they point out is the # used to make a heading. The tools will use the convention of taking the first # header and using it as the title for a post.

Most of the websites that I’ve come across will use title of a post as an h2 in order to denote that its semantically lower than the h1 they would have in the header of the page.

But, what about posts without a title? What about the person who isn’t familiar or not thinking about these details as they type away on their keyboards on that great post that will finally prove that whether pancakes or waffles are the superior breakfast item¹.

Other than testing whether the content has a title, the theme does not make any adjustments. It can’t automatically change all the headers and assume that the writer meant ### instead of ## for the sub-header.

Also, If we only navigate by headers and headers are only on titled posts, then what about the micro posts that micro.blog uses?

I’m not an accessibility expert, I just hope that whoever is using the theme, will be able to navigate using the different articles and aria-labels. I really hope that not having the headers isn’t a deterrent from reading the site. If you know of someone, please send me their information so that I can improve this site.

What would it take to change?

I was thinking about changing the structure of the theme to match the convention that I had seen with other themes. I’d make the articles have h2 and just go through all my posts to make sure everything had the proper heading.

In my local testing, I found that I ran into another problem where the built in table of contents feature of Hugo defaults to using h2 and h3 tags to create its content.

It’s documented on how to change the start and end levels but this would mean that users of the theme would see a change after an update. I can’t count on them reading the readme, being able to test it before hand, or going back to a previous version.

Ten Times the Technical Transform

About a month ago, I asked @help how many people were using this theme. Manton said 10.

I was shocked!

That’s 9 more than I was expecting.

I hope these people are happy with the theme - or so I imagine - and I don’t want to change that.

Withdrawn on the World Wide Web

The last reason is more personal.

I’m on the web, but I would rather you start reading what I wrote than read about me. Based off of my own web-surfing habits and the site traffic I get, I assume that when someone comes to the site they are coming from a direct link to an article. If that is the case, I want you to get to reading as quickly as possible.

The website has a title that is read by accessibility readers and shows up in the tab of your browser.

I don’t know how much of my traffic is people new to the site, but I do have an about me at the bottom of the page. It’s kind of a “find out more from this author” that you would see in the back of a book.

For me, this is more comfortable because I have trouble writing about myself. Ask anyone who has written a resumé, and they might say its easier to express how you think of feel about different things than it is to write about how you are really good at TPS reports.

Let’s head this off

This is not an attack on sites that use h1 for the title and have it at the top. I love those sites and the people that make them. This is just me explaining the theories of my own site. It’s not conventional and sometimes I look at it and want to start over.

It’s because of that burning feeling, I continue working on it.

Just running forward.

Without a head.

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!

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.

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 browsers¹!

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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 improvement¹, 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.

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.

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 forward¹.

<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.

This looked good in dark mode but not light mode.

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.

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.JS”². 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.

"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.

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.

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 false¹, the line that we’ve been looking at gets rendered to something like below.

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.

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

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.

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

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 diagrams² 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.

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!

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 Micro.blog 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.

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

93
Markdown diagrams and code block render hooks

94
20% reduction in build time and memory usage

99
Error handling release

101
Gif image processing

103
Updates to 404 support

104
$image.Colors

107
Update to code highlighting

108
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: github.com/gohugoio/…

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.

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 container¹.

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 code-blocks.md 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”²!

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.

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.

References

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.

ImageOptim

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

Excalidraw

I love making diagrams!

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.

• Floating Images
• Handling Transcripts
• No Longer Published
• Center Navigation Menu
• Changing the descriptions
• Removing Comments off the main page
• What’s next?

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.

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

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.

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

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

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 micro.blog automatically adds this for you. Thank you, @manton.

No Longer Published

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.

Styles

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.

Features

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.

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.

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.

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.

Colo(u)rs

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 micro.blog service.

Fonts

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.

Figures

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.

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

Tables

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.

Here it is in and 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.

Dark mode for the task list.

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 [developer.mozilla.org/en-US/doc...](https://developer.mozilla.org/en-US/docs/Web/CSS/list-style) */
}

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

Reflection

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.

Websites are read by more than just human eyes. Browsers, search engines, screen readers, and more take the information being served to them about a site and use it for different purposes. I wanted to make sure that my site could be parsed properly so that it can be reached to everyone who wants it. The web has several technologies designed for this purpose that do not add too much more work to incorporate them. I focused on Schema and OpenGraph meta¹ tags in the <head> element to achieve this. An excellent resource for learning about it can be found at HTML Head.

Preface

Hugo offers ways of doing this by having your template reference some internal templates. For example, the very popular template Ananke uses the following code to utilize these templates.

{{- template "_internal/opengraph.html" . -}}
{{- template "_internal/schema.html" . -}}
{{- template "_internal/twitter_cards.html" . -}}

At the beginning of this process, I found that including this would cause the site not to render on Micro.blog. That issue has since been resolved, but I kept with my code for my understanding and further customization.

The good thing about all of this is that Ananke has a link directly over the templates so that you can review the code yourself.

It can be found here: Embedded Templates

Another key difference is that the templates also have logic for a featured image. In most of my usage, I don’t have images and don’t know how to specify an image as featured in markdown. I’ll have to reevaluate this at a later date.

Heading Home

When creating a template for blog, you should be aware that not all tags that you would have for your articles apply to your main page.

I used a flag that Hugo provides to create a section in the header for the home page to keep tags that a specific t the landing page.

{{- if .IsHome -}}

For the individual articles, I’ll be checking the title property in to determine logic on what tags that will be used.

{{ if isset .Params "title" }}

When you read the article, you will see different times that I specified something and may think that I could have been more clever by writing it in a way where I don’t have to repeat myself. I did this for a few reasons.

1. I’m learning how Hugo works with templates
2. I find that clever code can be difficult to debug and understand (You can thank me later, future me)

Getting a head of the page

I wanted to start off with the <head> elements that Micro.blog uses before checking to see if there were other things that I needed to add for the website.

I like to look at the Marfa’s head partial because it’s the theme that Manton uses.

{{ "<!-- Micro.blog Values -->" | safeHTML }}
<link rel="shortcut icon" 
	href="https://micro.blog/{{ .Site.Author.username }}/favicon.png"
	type="image/x-icon" />
<link rel="me" href="https://micro.blog/{{ .Site.Author.username }}" />
<link rel="authorization_endpoint" href="https://micro.blog/indieauth/auth" />
<link rel="token_endpoint" href="https://micro.blog/indieauth/token" />
<link rel="micropub" href="https://micro.blog/micropub" />
<link rel="microsub" href="https://micro.blog/microsub" />
<link rel="webmention" href="https://micro.blog/webmention" />
<link rel="subscribe" href="https://micro.blog/users/follow" />
<link rel="canonical" href="{{ .Permalink }}" />	

A lot of the these values are specific to how Micro.blog and the open web respond to the site in general. Blogging software such as MarsEdit, will use this information to connect to your blog for editing. Webmentions are a way for different systems to communicate to regarding if the source content has been referenced somewhere else.

{{ if .RSSLink -}}
<link href="{{ .RSSLink }}" rel="alternate" type="application/rss+xml" title="{{ .Site.Title }}" />
      <link href="{{ "podcast.xml" | absURL }}" rel="alternate" type="application/rss+xml" title="Podcast" />
      <link rel="alternate" type="application/json" title="{{ .Site.Title }}" href="{{ "feed.json" | absURL }}" />
      <link rel="EditURI" type="application/rsd+xml" href="{{ "rsd.xml" | absURL }}" />
    {{ end -}}

These allow for newsreaders and podcast aggregators to get the information needed to get information about updates. One cool thing is the use of a JSON feed that Manton helped build.

I also found a website dedicated to explaining a lot of the different tags that can be found in the <head> element.

Open examples

The first set of tags that I looked at were ones related to OpenGraph tags. These where the ones that a supported in social media (facebook, twitter, slack, etc.) and operating systems that I was using at the beginning of the project.

OpenGraph tags behave the same way as <title> and other tags in a web page. In fact, for some services, if an OpenGraph tag is not there, it will default to other tags in the head. For example, title or description. I decided to define the values for the tag to make sure that the site is compliant².

The key difference between OpenGraph tags and the standard tags that you see in the <head> element of a website is that they are defined as <meta> tags. A tag would have a property and content definition that would follow a pattern shown below.

<meta property="PropertyName" content="PropertyString" />

In the examples that I have seen, they often duplicate some of the information that is already there. In most cases, you would see:

<title>Some Title</title>
<meta property="og:title"
  content="Some Title" />

This makes it fairly effortless to get most of the tags together with only a few complications with dates, images, and whether to support twitters extensions.

Dates

A long time ago, some smart people decided that there should be an international standard for representing dates. As of this writing, Hugo doesn’t automatically format the date to this standard.

{{ $iso8601 := "2006-01-02T15:04:05Z07:00" }}

This line defines a string that we can use to later format dates in other parts of the template.

{{- with .PublishDate }}
<meta property="article:published_time" {{ .Format $iso8601 | printf "content=%q" | safeHTMLAttr }} />
{{ end }}

Then when a page is rendered we can see the time and in which time zone.

<meta property="article:published_time" content="2023-03-23T16:50:58-07:00" />

Images

For the home page, we assume that the user wants to use their favicon for their image property.

<meta property="og:image" content="https://micro.blog/{{ .Site.Author.username }}/favicon.png" />

This works fine for home pages, but we want to provide more information for the articles that may have it.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{{- with .Params.images -}}
{{ "<!-- .Params.images -->" | safeHTML }}
<meta name="twitter:card" content="summary_large_image" />
{{- range first 6 . }}
<meta property="og:image" content="{{ . | absURL }}" />
<meta itemprop="image" content="{{ . | absURL }}" />
{{- end -}}
{{- else -}}
{{ "<!-- $.Site.Params.images -->" | safeHTML }}
<meta property="og:image" content="https://micro.blog/{{ .Site.Author.username }}/favicon.png" />
<meta itemprop="image" content="https://micro.blog/{{ .Site.Author.username }}/favicon.png" />
<meta name="twitter:card" content="summary" />
{{- end -}}

The first line checks that images exist in the article.

Line 2 creates a comment in the rendered HTML.

Line 3 is specific to twitter makes the images bigger in the timeline.

Line 4 sets up loop over an array. The key words first 6 limits the loop and the . specifies the array as being the images defined in .Param.images.

Line 5 creates the line of html for that particular image we are on in the loop.

Line 8 starts our logic when there are no images attached to the article and defaults to giving the user profile picture.

Other media

Modern sites can also have audio and visual components as well.

{{- with .Params.audio }}{{ range . }}<meta property="og:audio" content="{{ . }}" />{{ end }}{{ end }}

The line looks at all the audio in the article and then adds the following property.

<meta property="og:audio" content="https://micro.blog/pages/downloads/661/1841919/750047.mp3" />

You can also do the same looping code to go over any video that you might have.

{{- with .Params.videos }}{{- range . }}
<meta property="og:video" content="{{ . | absURL }}" />
{{ end }}{{ end }}

And it will render correctly.

<meta property="og:video" content="https://mandarismoore.com/uploads/2021/793e8ba1bb.mp4" />

At the moment, I don’t have an examples of a system processing this information, but I’m happy knowing that it’s there.

The Twitter Question

As I was working on this, Twitter was acquired by Elon Musk. There were numerous layoffs and I honestly don’t know if I should put in the time to make sure that I support the twitter specific extensions to the OpenGraph specs. Ultimately, I added them in case someone uses this theme and shares the links on Twitter.

Micro.blog allows a user to add their twitter name and I used that to populate both twitter:site and twitter:creator.

1
2
3
4
5

{{ with .Site.Params.twitter_username }}
<link rel="me" href="https://twitter.com/{{ . }}" />
<meta name="twitter:site" content="@{{ . }}" />
<meta name="twitter:creator" content="@{{ . }}" />
{{ end }}

If the user doesn’t have a twitter username, this code will not be included during the rendering of the website.

Scheming

The key difference between OpenGraph and Schema tags is that they use different tags to represent the same information.

A schema meta tag will usually look like the following.

<meta itemprop="PropertyName" content="PropertyString" />

This is basically the same idea but implemented by different groups. When I first learned of Schema tags, I was told that it was used by search engines to parse information. When I attempted to verify this, half the tools used to check have been shutdown or made reference to using OpenGraph.

Still, I wanted to include them as the logic was already completed during my implementation of OpenGraph tags.

In addition to the meta tags, you will see the schema tags in the article itself.

For example, in the <span> tags of the article footers for the different dates and categories.

<span itemprop="articleSection">{{ $Category }}</span>

Currently, I’ve mixed in all the schema tags with the OpenGraph tags to make sure that I have parity between the two where it makes sense.

Evaluating

For open graph testing, I created a page on the test version of my site using the two following tools.

https://opengraphr.com/open-graph-debugger

https://www.opengraph.xyz/

Schema

I used https://validator.schema.org to test Schema.

Accessibility

I used https://wave.webaim.org to test for accessibility. I did get some alerts with the design because I had some video and audio tags but no transcripts. Another issue is the contrast that I used for the Permalinks on dates. I’ll work on that in a future release.

twitter

The twitter official validator is https://cards-dev.twitter.com/validator. NOTE Removed as of mid 2022. You have to post the link in the composer window of a tweet to see what it will look like.

Opportunities to grow

During the writing of this article, I found numerous ways that I can improve my theme. So much, that I had stopped development because I didn’t want the article and theme to become too separate from each other.

To continue with development without worrying about this, I’ve tagged the version of the code for the time that these steps of the article were created. You can find the link below.

Labarum 1.0.1

In the meantime, I’ll be cleaning up the code so that the Hugo Theme is easier for me to read and that the rendered output as well.

I tested the accessibility of the site, and it did have a decent score, but I’d really like to improve the fonts and colors.

You are welcome to follow this site or the Labarum category to see updates when this is updated. And you can always contact me here or via email!

Other posts in this series

Creating Labarum Part 1: Design and initialization

Creating Labarum Part 2: Creating the individual posts

Creating Labarum Part 3: Implementing post footer

Creating Labarum Part 4: Initiating the Index

In the beginning of this series, we started off with an index page that was just a static page with one line that stated you were on the index page. When it comes to implementing this, I looked at the Hugo Themes Free as well as the theme gallery that Micro.blog provides.

Ultimately, I went with a simple structure that took advantage of the simplicity that I had in the Pure theme and the fact that we had already extracted the logic for articles into the partials.

{{- range ( .Paginate (where .Site.RegularPages "Type" "post")).Pages }}
{{ partial "article.html" . }}
{{ end }}

After that, we remove all the static <article> tags that we placed into our index to see how it renders. This looks ok, but the design that I have in mind calls for pagination¹(being able to go to older posts).

Paging the index

I admit that I went down a rabbit hole of different examples of how to create the navigation that you see at the bottom of the page. A lot of the examples that I came across where hard coded or I couldn’t understand.

Ultimately, I went with the example that I had from my previous theme. I took the code and placed it into a file name partial\site-navigation.html so that I can track it later.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

{{ "<!-- Site Pagination -->" | safeHTML }}
{{ $paginator := .Paginate (where .Data.Pages.ByDate.Reverse "Type" "post") (index .Site.Params "archive-paginate" | default 10) }}
<nav class="pagination">
	{{- if $paginator.HasPrev -}}
	<p class="nav_prev">
		<a href="{{ $paginator.Prev.URL }}" title="Previous Page" rel="prev">
		← Newer Posts
		</a>
	</p>
	{{- end }}

	{{ if $paginator.HasNext -}}
	<p class="nav_next">
		<a href="{{ $paginator.Next.URL }}" title="Next Page" rel="next">
		Older Posts →
		</a>
	</p>
	{{- end }}
</nav>

On the first line, I’m adding a line that will show up in the final output of the generated site so I can see where Hugo is inserting the code.

The second line calls the default paginator to go over all the posts that the site has by whatever parameter that is given. If none is given, it will use 10.

Line 3 defines our semantic element for the navigation and give it a class for styling it later.

Line 4-10 tests to see if there is a previous page and then creates a link to the page when it exists.

Line 12-18 tests to see if there is a next page and creates everything that’s needed.

Navigation

The navigation was another thing that I spent a lot of time looking into, but ultimately went with a simple ordered list of items.

The initial design did not have a link to the home page because I thought that anyone how came across the page would only be interested in that page and not the additional content, but after having to go to the address bar multiple times to navigate between the different pages, I decided to add it as the first item.

I placed this into a separate file called site-nav.html like I did for pagination for better tracking.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{{ "<!-- site-nav.html -->" | safeHTML }}
<nav>
	<menu>
		{{ if ne .IsHome true }}
		<li><a href="{{ .Site.BaseURL }}" title="{{ .Site.Title }}">Home</a></li>
		{{ end }}
		{{- range .Site.Menus.main }} 
		<li><a href="{{ .URL | relLangURL | safeURL }}">{{ .Name }}</a></li>
		{{ end -}}
		<li><a href="{{ "feed.xml" | absURL }}" rel="feed" type="application/rss+xml" title="{{ $.Site.Title }}">RSS</a></li>
	</menu>
</nav>

On line 3, I used the <menu> semantic tag to give it some more meaning. It definitely felt that it took some time to On line 3, I used the <menu> semantic tag to give it some more meaning. It definitely felt that it took some time to get a consensus on whether I needed to add a <ul> or <ol> to make the syntax valid.

Line 4 does a test to see if the generated page is the home page. This is working to an extent, but fails when moving to the second index page.

Line 7 sorts through the different menu items. I had an issue trying to understand how Hugo puts together a menu on my local copy and what was being used in Micro.blog.

Line 10 gives a direct link to the RSS feed for the site. The RSS feed is inherited from the base blank theme that underlies of Micro.blog.

The next segment of this tutorial will be focused on the schema tags followed by accessibility and then a grab bag of different things.

Please let me know if you have any questions about the design so that I can make this better. I think I might put this all together in one LARGE post at the end.

In my initial design, I had footer that would show the categories, tags, date published, and date modified. All of these values are things, I had seen in previous sites and I could easily get to this information. I thought it would be 15-20 minutes to get this information. The fact that I felt that the footer deserves it’s own discussion should let you know that it ultimately wasn’t.

Start!

The first thing I did was move my current static footer from my example into it’s own template file partials/article-footer.html. I’m going to spare you the boring details of how I searched and searched through examples of what I thought it should look like versus what Hugo provides. A lot the issues that I ran into was whether I was using tag, tags, category, or categories. Do I write the code I write have to parse a comma separate list or an array?

My mental model originally had it so that a post could have one category and multiple tags.

Unfortunately, after a couple hours I realized that a lot of this was moot because I was going to send this template to Micro.blog and I didn’t know what they used.

Getting more information about Micro.blog

The ultimate goal for this theme is that I’d use it on the Micro.blog service. Although Micro.blog uses Hugo, it has a significant amount of customization that I do not know about. Honestly, I do not want to know exactly how it is put together, but I do want to know what it is sending to the theme to get rendered.

So, this is the point in the process where I deploy all the changes that I’ve made to GitHub and then use the instructions on how to set up with a custom theme.

I took some information from the  Hugo page on debugging a theme and then placed that in a <detail> item nested in the  footer. This made the article.html template pretty long, so I decided to make the footer into its own file (article-footer.html) for easier management.

Ultimately, this allows me to see if Micro.blog supports tags or categories and whether it’s stores in a string or array. I’m going to include the code in this post below.

{{ "<!-- Debugging Details --> " | safeHTML }}
	<details>
		<summary>Debug</summary>
		<h1>Site Properties</h1>
		<pre>
		{{ printf "%#v \n" $.Site  }}
		</pre>

		<h1>site.Params Properties</h1>
		<pre>
		{{ printf "%#v" site.Params }}
		</pre>

		<h1>Permalink</h1>
		<pre>
		{{ printf "%#v \n" .Permalink }}
		</pre>
		
		<h1>Params</h1>
		<pre>
		{{ printf "%s" $.Params }}
		</pre>

		<h2>All variables scoped to the current context</h2>
		<pre>
		{{ printf "%#v" . }}	
		</pre>
	</details>

After that, I’ll set the display of the debug information to hidden in the CSS.

article footer details {
    display: none;
}

I then deploy it to the test blog to see what is going on, I can see that categories is used in templates and is stored in an array.

If we parse through the debug information, we can find the information about whether Micro.blog uses tags or categories.

Categories and Tags

As you have seen, I spend a lot more time of what the different elements make up the different pages. From here, I borrowed¹ some code from the internet and rewrote it so that I can hopefully remember what it does in the future.

{{ with .Param "categories" }}
	Categories:

	{{ range $CategoryArray, $Category := (. | sort) }}
		{{ if gt $CategoryArray 0 }}
			<span>•</span>
		{{ end }}
		<a href="/categories/{{ $Category | urlize }}">{{ $Category }}</a>
	{{ end }}
	
{{ end }}

I also included code for tags that I saw in another example to future proof the theme in case we add tags later on with Micro.blog.

{{- with .Param "tags" }}
{{ with $.Param "categories"}}
<br />
{{ end }}
	Tags: <span itemprop="keywords">
  	{{ range $index, $tag := (. | sort) }} 
  		{{ with $.Site.GetPage (printf "/%s/%s" "tags" $tag) }}
  			<a href="{{ .Permalink }}" class="tag">{{ $tag | urlize }}</a>
  		{{ end }}
	{{ end }}
	</span>
{{- end }}

I didn’t do much with this portion because we don’t use them with Micro.blog, and I’ve got a lot of other things to get working before coming back to this.

Remember the time

Another piece of information that we can get from the debug output is date information from the post. We actually get three different dates: date, publishdate, and lastmod.

On my local server instance, I played with the different logic for if a date was different than another and learned about how Go did comparisons of dates for about an hour.

Then I found out that Micro.blog use the same time for all three…

You can then put this information into our template.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<p>Published: 
	<a href="{{ .Permalink }}" class="u-url">
	<time class="dt-publised" itemprop="dateCreated datePublished"
		{{ 
		printf `datetime="%s"` (.Date.Format "2006-01-02T15:04:05Z07:00") 
		| safeHTMLAttr }}>
		{{- .Date.Format (default "January 2, 2006" .Site.Params.date_format) }}
	</time>
	</a>
</p>

On line 2, I create a link to the article because this footer will be used single pages and the index and we don’t know if every post will have a title.

Line 5 makes sure that the date is formatted in ISO 8601 so that it can be parsed properly.

Line 7 shows the date in a more human readable way. I made a mental note to look into how I can make it output “6th” but all the examples that I’ve seen do not show in like that.

Styling the footer

I wanted the footer to have two separate sections of information; one for categories and tags and the other for dates.

I used a css grid to make the two sections and made sure that the data I add was grouped in a <p> tags.

article footer {
    display: grid;
    grid-template-columns: 2;
}

article footer p:last-of-type {
    grid-column: 2;
    text-align: right;
}

After doing my testing and getting the debug information, I hid the details in the footer.

article footer details {
    display: none;
}

I plan to cover more css when I discuss accessibility later on in the series.