A few quick notes about building Micro.blog themes

It took me just a few days to convert the Cypress WordPress theme for use on Micro.blog. Since the layout, design, and styling for most elements was already done – the main work was learning Micro.blog’s theming model and moving the code bits around.

I thought it would be a good opportunity to jot down some observations since I was totally new to the theming model that Micro.blog uses. Perhaps this information will be useful to you.

Before I list my observations, let me just put out this call to action. If you’re reading this and have any abilities as a web developer, it is very simple to convert just about any website theme from any other platform into a Micro.blog theme. You should consider doing it to help the ecosystem around M.b grow. The team there is small. So helping them even a little bit will go a long way. If themes aren’t your thing, perhaps a plugin.

Here are my observations in no particular order:

  • M.b’s theming model is based on Hugo, a “static website engine”
  • The files are primarily standard HTML files with some curly brackets {{ }} for including other files, logic, loops, etc.
  • Your theme is not an island. A custom theme’s files supersede and replace the files in the blank theme that M.b uses. If you include a file (E.g. index.html) in your custom theme, it replaces the one in blank, but if you don’t, it will use the blank one instead. (I may be explaining this incorrectly, but at least this is my understanding)
  • Because M.b is very light on features, most themes need only consist of a few files to support most features
  • It pays to study the “lookup order” of Hugo themes. Like WordPress (which is far more complicated), any given URL can result in different files being loaded. By knowing this order it can cut down on frustration a bit.
  • M.b has a bunch of themes open sourced on their Github. Looking through each of those helps a lot.
  • M.b’s theme documentation is lacking. I’m sure this issue will get better over time now that the new Help Center is online. The more questions we ask and answer in this area, the more people will benefit.
  • If any M.b member makes any edits to a theme using the web editor, they will break their ability to get updates of your theme. I don’t see anyway around this, but it should be known.

Here is my workflow for testing and updating Cypress on Micro.blog. It is a little cumbersome, but no big deal in the grand scheme of things. I’m sure this workflow will improve with time.

Side note: I was running Hugo locally in a Docker container but I quickly abandoned that. M.b is unique enough in its feature-set that I found Hugo to not be a good environment to test against. Perhaps if I spent more time creating a M.b-like environment it would have cut down the number of builds I’ve had to push to the site.

  1. Commit changes locally using git.
  2. Push changes to the main branch on Github.
  3. Log into M.b, click Design, click “Edit Custom Themes”, click “New Theme” and add a new theme with a version number (E.g. 2021.1.0b) – I would change this version number with every build I pulled from Github to bust M.b’s cache. It didn’t always work, but it worked most of the time.
  4. Go back to Design settings page, set the theme for my blog to “Blank”, select my Custom Theme from the list, click “Update Microblog Settings”.

It would typically take 5-10 minutes for my changes to show up on my test blog.

Obviously, this isn’t ideal. So I recommend batching your updates as much as you can.

Once I had a build of Cypress that seemed to work as I had planned on the test blog, I would then set the version in the head.html file (see Line 4). Update the readme. Commit those changes. Push to Github, and tag the release. By setting the version in the head I’m able to determine what version someone is running when a bug is reported.

Lastly, a few tips:

  • The “photos” page is special for Micro.blog. There is a button under your Pages settings that says “Add Photos Page” if you don’t already have one. M.b. will filter out posts that have images in them to populate that page with content. It is a very different approach.
  • As far as I can tell, M.b loads images that are in posts in full resolution. The same goes for most indexes too. This can make page load times very, very long in some cases. One way to mitigate that is to turn on pagination so that there aren’t so many posts loaded per page. This is done in the config file. Another way is to use M.b’s thumbnail creation API. As far I know, this isn’t documented anywhere. If it is, I missed it. But it is in use. You can reverse engineer the URL structure yourself. Here is an example URL: https://micro.blog/photos/480x/{{URL TO IMAGE GOES HERE}} – This will dynamically create a new image 480 pixels wide. You can see this in use here.
  • There is a page for /archive even if a Microblog doesn’t have that in their navigation. So I’d recommend including a list.archivehtml.html file in every single theme.

That’s about it. Hugo themes are a learning curve and are likely far more powerful and flexible than even M.b currently has use for. Once you wrap your head around how it works, it is pretty simple to convert a theme and I think it’d be great if more people did so.

Lastly, if any of the above is totally incorrect, please let me know and I’ll correct it.