Mark R. Stoneman

The transition from Wordpress.com to Micro.blog was challenging because of the initial difficulty I had in finding and customizing a theme that worked for me. They either did not feel right to me, or I couldn’t find sufficient documentation. This problem was multiplied by insufficient knowledge about Hugo (the blogging software) and Go (the language Hugo uses).

I initially passed over Tiny Theme because I did not appreciate its developer’s approach, but pouring through the Micro.blog help forums led me to try it again. Armed with a little more knowledge, I began to appreciate what the theme offers.

Tiny Theme is the best-documented theme on Micro.blog. Besides the Git page, its creator, Matt Langford has a dedicated Tiny Theme site, written in plain language that assumes some knowledge of blogging and markup, but not overly much.

Matt also generously answers questions, but do your research first—both as a common courtesy and so you understand his answers.

I think his “leave a tip link” recalls the great tradition of shareware, which Apple’s app store has undermined in the MacOS world. Why not honor his work and keep such a tradition alive at the same time?

Future-Proofing

The theme is built to be adaptable without changes requiring too many interventions in its core templates. One can still edit those, but Matt wrote the templates to look for a user’s customizations in files called microhooks. This makes updating the theme much easier.

Update-proofing matters because Matt regularly maintains and updates the theme (in useful ways, not ways that require you to rethink everything).

In this respect, it is better to use your Micro.blog custom CSS page than to change the theme’s CSS directly.

This last point about CSS is critical for making a move to another theme possible. A lot of CSS customizations are specific to a theme, but you have some that are not theme-specific, e.g., small image galleries.

If you customize one of the theme’s core templates (as opposed to the microhooks you write from scratch), write down what you did. You will need this information later. See below for your own customizations.

Updating Tiny Theme

⚠️ When you see an update is available in Micro.blog’s plugins UI (where the themes are stored), do not hit the update button. Instead, first go to Github to see which files have changed. (It’s an easier UI for scanning modification dates.) Make a note of their names. Then hit the update button in the pugins UI.

⛔️ Never click the 🔄 button on the Micro.blog theme management page. Despite its emoji, it does not sync your files. It just downloads from the Github repository and overwrites your customized files, except the microhooks. You don’t need this functionality,

After that, your theme files in Micro.blog’s theme editing UI (menu item: Design) will all still be intact. Below that section are the unedited theme files. If you have modified any of the files that that were updated, see the next step. Otherwise you’re done (except to eyeball your blog for any apparent issues).

Assuming you have taken notes on your modifications to any of the theme’s templates that were updated, you first delete these modified files from the customization section, and then you modify and save the same changes in the section that holds the themes unmodified files. As soon as you do that, Micro.blog saves the file you your customized templates and restores the original template to the theme files section.

This setup relates to the lookup order of Micro.blog’s Hugo rendering engine: It first looks if the necessary template is among the customized files. If it finds it, that’s the one it uses to output that (part of the) page . If not, it looks to the original theme files. (If here either, it looks to Micro.blog’s default files.)

My Modifications

This section does not include the microhooks, since the theme doesn’t touch their contents.

layouts/_default/list.html

This file renders category pages on Micro.blog. I merely added “Category: " before the page title (the category name) in the following block.

<h2 class="p-name">Category: {{ .Title }}</h2>

layouts/_default/list.archivehtml.html

This is the template renders the archive page on Micro.blog, if you have enabled the page in Micro.blog’s UI.

Main issues with Tiny Theme default:

1. The categories are not alphabetized.
2. The categories render as a long vertical list.

I needed alphabetical order and a format that worked better for all my categories than a vertical unordered list. (I have a lot of categories because Micro.blog is only set up for categories, not categories and tags.)

Tiny Theme has a microhook to add introductory material to the archive page, so that bit is not at issue here.

Original section section of this theme page

<div class="archive-categories">
<h3>Categories</h3>
<ul>
{{ range $list }}
<li><a href="{{ .Permalink }}">{{ .Title }}</a></li>
{{ end }}
</ul>
</div>
{{ end }}

Modified section

I was able to get most of the following by copying and pasting from a file in the notes of a short YouTube video by Vlad Campos. I fooled around a lot with it,¹ but I think I ended up just replacing the span tags with paragraph tags, which seems to have made CSS styling possible. (The indentation differences between this section and the original make no difference to Hugo, as far as I can tell.)

<div class="archive-categories">
<h3>Categories</h3>
<p>
{{ $sortedList := sort $list "Title" }}
{{ $length := len $sortedList }}
{{ range $index, $element := $sortedList }}
<a href="{{ $element.Permalink }}">{{ $element.Title }}</a> {{ if lt $index (sub $length 1) }}{{ end }} 
{{ end }} 
</p>
</div>
{{ end }}

Update (Oct. 10, 2024): Additional Modifications to Archive Page Template

Change the <p class="h-entry"> block to the following:

<p class="h-entry">
<a href="{{ .Permalink }}" class="u-url"><span class="dt-published" datetime="{{ .Date.Format "2006-01-02T15:04:05-0700" }}">{{ .Date.Format "Jan 2, 2006" }}</span></a> - 
{{ if .Title }}
<a href="{{ .Permalink }}" class="u-url"><span class="p-name">{{ .Title }}</span></a>
{{else}}
<span class="p-summary">{{ .Summary | truncate 140 }}</span>
{{end}}
</p>

This changes the bold titles to normal font weight while also adding links to the titles. It also removes summaries from posts that have titles and truncates untitled posts at 140 characters.