FAQ

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.

More resources

• Hugo Documentation
• Custom themes - Documentation - Micro.blog Help Center

This post explains how to update your already installed Cards Theme for Micro.blog to the latest version.

You’ll see an update to the Cards Theme for Micro.blog on your Micro.blog Plug-ins page if there is one.

• Open your Micro.blog account.
• Select the Plug-ins page in the left navigation.
• Check your Cards Theme for updates. If available, it will resemble the screenshot below, showing the available and an Upgrade button.

• Click the Upgrade button.
• Wait a moment and refresh. The Cards Theme plug-in should show the current version and the Update button will disappear.

You now have the latest Cards Theme update!

The Cards Theme is a custom theme for Micro.blog based on the Hugo templating engine.

You must have a Micro.blog account to use the Cards Theme. Custom Themes can be installed as Plug-ins.

• Go to your Micro.blog account page.
• Select Plug-ins in the left navigation. This page will show all the installed Plug-ins for your blog.
• Select the Plug-in Directory button at the top to search for installable Plug-ins.
• Search for “Cards Theme” and click Install to get the latest version.

• After a few moments, refresh your Plug-ins page. It should now show your Cards Theme under Installed plug-ins. If you had a previous theme installed, it will remain listed in your plugins, but disabled.