Custom Theme Tips

This page is a work in progress. Last updated January, 2023


Making a custom theme for your Micro.blog isn’t as impossible as it may first seem. Be kind to yourself, work in small chunks, and prioritize needs over novelties. It’s your custom theme so you can always add more shiny new things later.

1. Install Hugo

Designing a theme requires a lot of trial and error. Change a value, save, look at the results, repeat. The ideal place to do that is on your own computer where you can see your changes instantly. (You won’t even need to be on the internet!) That is why the first step is to install Hugo, the static blogging engine that makes Micro.blog work, on your computer.

As of writing this, Micro.blog only supports two versions of Hugo so the first step is to decide on and download one of those two Hugo versions: version 0.54 or version 0.91 (I recommend version 0.91) Use the official documentation to install Hugo on your operating system.

2. Get Your Own Content to Work With

After Hugo is locally installed on your system, I highly recommend populating it with your blog’s data. Things make more sense when you are working with your own stuff.

  • While logged into Micro.blog, visit your Posts page
  • At the top of the page, to the right of your blog’s URL, is an icon of ellipsis within a circle “…”
  • Click the icon and, in the popup menu that appears, click Export. You will be taken to an export page where you can download Export theme and Markdown together.
  • Copy those downloaded files into the content folder of the local site Hugo created.

3. Stand On the Shoulders of Giants

Unlike in school, everybody online is looking at each other’s work and you should too. If there is a theme you already like, download it into your local Hugo install. Poke through it, learn how it works, and remix the bits you like into your own theme. Some theme authors might also answer questions so don’t be afraid to reach out and ask how they did a clever thing you like.

With those three things completed you’re ready to run Hugo’s server function, fire up your editor, and start designing your custom theme. :smiley: Happy coding!

Don’t forget:

  • Your custom theme requires a free Github account and Git installed on your system. (I personally like using the GitHub Desktop app.)
  • You don’t need to upload your entire local Hugo structure to GitHub, just the theme itself.
  • Micro.blog’s help site has many good answers. I was suprised at how well searching worked. The introductory Custom Theme article is a good place to start.