How Micro.blog Handles Theme Customizations and Updates
In this post, I’ll explain how Micro.blog manages theme files with a layered system and how this affects your ability to update or customize packaged themes like the Cards Theme. To personalize your blog’s appearance while still receiving theme updates, it’s important to understand this process.
How Layers work
Micro.blog uses Hugo, a static site generator, to build your blog. Each time you add a theme or plugin, you add a new “layer” of template files on top of the default ones. The system always uses the file from the highest available layer.
If two layers have a file with the same name and path (e.g., layouts/post/single.html), the higher layer’s file is used, and the lower layer’s is ignored. Your customizations always take precedence over packaged theme updates unless you delete your custom file.
| Layer | Template File | Source | Used? |
|---|---|---|---|
| 3 | layouts/post/single.html | Custom Theme | Yes |
| 2 | layouts/post/single.html | Cards Theme | No |
| 1 | layouts/post/single.html | Default | No |
Custom Themes
To customize template files, add custom CSS, or create a custom footer, create a “Custom Theme” from the Design page in your account. This adds a layer on top of the existing ones.
Micro.blog manages these layers for you, so you don’t need to think about them unless you customize template files, which can be confusing.
When you view your template files in Micro.blog, you see all the files but can’t tell which layer they come from. Manton designed it this way to hide the complexity of layers and always show the top layer. You can assume the file you see is the top layer used to create your site.
A clue that a file is custom is that it appears at the top of the list.
What happens when the Cards Theme files are updated?
When the Cards Theme (or any packaged theme) releases an update, you are prompted to update the theme. All theme files are updated in the same layer where they were originally created, in this case, Layer 2.
If you have copies of these files in your Custom Theme (Layer 3), you will not see updates from the Cards Theme and will continue to see your own customizations.
How do I ensure I have the latest Cards Theme files?
To use the latest files from the Cards Theme, delete the custom files in your Custom Theme. For example, if your layouts/post/single.html file is different from the Cards Theme version, delete it from your Custom Theme. Micro.blog will then use the file from the Cards Theme. This will remove your customizations, so make a backup first.
To add your own customizations, copy the file contents from the Cards Theme, create a new file with the same path and name, paste the contents, and then make your edits.
A walkthrough of overriding specific template files:
I created a new blog and installed the Cards Theme. On the Design page, I noticed that Micro.blog had already applied a “Custom Theme” automatically for convenience.
When I opened my custom theme, I saw all the Cards Theme files as expected. Inspecting layouts/post/single.html, I confirmed it matched the original Cards Theme file.
Test posts rendered as expected.
In my Custom Theme, I clicked the New Template button, added layouts/post/single.html as the file name, and pasted the content from the Cards Theme file. I then made the modifications shown in the highlighted text below.
When I open my test post, it displays my customizations instead of the default post content.
To revert to the Cards Theme version, I selected layouts/post/single.html from my Custom Theme files and deleted the template.
After publishing, the default Cards Theme layout was restored.
Conclusion
I hope this was helpful and not as confusing as it seemed when I wrote it. There is a lot of nuance here. One thing I’m still unsure about is how to determine if your file is customized. If Manton reads this, perhaps he can clarify or consider it as an enhancement request.