• Paper theme upgrade — favicon

    I have released a new version of the Paper theme today. It’s a minor upgrade that allows you to set a custom favicon through the theme settings. Of course, it is optional. If you do not configure it, the default Micro.blog favicon will be used. The upgrade is available now.

    14 August 2022

  • Plugin: Home page photos

    Manton says on 24 July 2022:

    Hello, photo bloggers! I created a new plug-in that replaces your home page with a grid of photos and links for your other pages. No post text on the home page. Hope it’s a good start for people who want to go all-in on photos. Called simply “Home page photos”.

    Update — a question: Can I customize the theme like any other theme? I want to remove the "Follow at Micro.blog" links.

    The answer: You can hide that with CSS... Paste something like this in Design → Edit CSS: .me .description { display: none; }

  • Manton on Micro Monday 112

    It’s worth listening to Micro Monday - 112: Manton (@manton) on the latest new things for Micro.blog (27 minute podcast) for news and information about:

    some of the new things that have been added to the platform just lately, such as:

    • Location features
    • New themes: Gateway and Alpine
    • Font Awesome plug-in
    • New status bubble
    • No Robots plug-in for disabling search engine indexing
    • Indie Microblogging book status update
  • Alpine theme

    I extracted the design I use on manton.org into a new Micro.blog theme called Alpine. It’s like Marfa, but with a smaller header and settings for changing the color of the “Also on Micro.blog” button.

  • Plugin: Font Awesome icons

    I made a Micro.blog plug-in that loads Font Awesome in your blog, so it’s easier to add icons to blog posts or to use them in theme templates.

    Update, 01 July 2022:

    After I made the Font Awesome plug-in, I recorded a video about using it, including how Micro.blog themes work. There was a caching bug in the video, so wanted to re-record it after fixing it… But I don’t have time, so posting the video anyway! Enjoy, it’s on YouTube here.

  • Link: Gateway theme

    Had some fun with Micro.blog themes and created a new one for those “link in bio”-style sites. It has a custom home page with links to other platforms, but because it’s Micro.blog it can still have a full blog underneath. It’s called Gateway. Demo here: links.manton.org

  • Plugin settings parameters

    Micro.blog plug-ins can have a settings screen to change config parameters. I’ve added a new field type “color” that I’m hoping will be useful to customize the design of more themes. Modern web browsers provide a color picker for these. (Example config for this screenshot.)

    Color config screenshot

  • Link: Coffee shop photos template

    Manton Reece - Coffee shop photos template:

    I thought it would be fun to create a page on my blog that just shows coffee photos. …
    The next step was to create a template layouts/_default/coffee.html in my custom theme that would pull posts from this category.

  • Link: Better change log for Micro.blog features and fixes

    This may be useful for those creating or editing themes and other custom features of their Micro.Blog.

    Manton Reece says in Better change log for Micro.blog features and fixes:

    We’ve come up with a new way to document changes to Micro.blog. In the past, we usually only note big changes on @news or on my own blog, so everything is scattered and small changes are rarely even mentioned. To fix this, there’s now a special category on news.micro.blog that will list most changes to the platform, both big and small.

    I’ve customized the news blog home page and feed to exclude these posts, so if you’re following @news, you won’t get all the noise of the day to day changes that we roll out. And because it’s all powered by a normal Micro.blog-hosted blog, it’s something that is easy for us to maintain. If you really want to know about everything, you can also subscribe to this RSS feed.

  • Link: Width and height of photos on Photos page

    Manton says at the Micro.blog Help Center, Width and height of photos on Photos page?:

    I’ve rolled out a change inspired by @kottkrig’s feedback. In the front matter, there is now a new “photos_with_metadata” with 3 fields: “url”, “width”, and “height”. I haven’t done much with this yet other than to confirm it’s working, but hopefully this opens up some more custom theme and plug-in possibilities.

    11 June 2022

  • Link: How do I create a custom theme to show location data?

    Link: How do I create a custom theme to show location data?:

    What you have to do is:
    > 1. Create a custom theme.
    > 2. Update the template layouts/post/single.html to include your location information.

  • Link: Creating a Micro.blog Theme + Tailwind

    Zoe Aubert: Creating a Micro.blog Theme + Tailwind:

    I decided I wanted to have a go at building my own them. At first, the challenge seemed relatively easy as there were many other themes already out there, but I was soon to be proven wrong. Hopefully, I can steer you in the right direction to save you some time.

  • Paper theme now correctly works with On This Day

    I recently got to know (h/t Gabriel) that “On This Day” feature doesn’t work with the Paper theme. I fixed the issue – the micro memories should load properly now. I have also fixed a few minor styling issues. The upgrade should be available in the plugins directory now.

  • Link: Hain's Point Theme

    Hains-Point: A theme for micro.blog:

    A customizable newsletter-focused theme for Micro.blog. Includes featured posts, asides, and more!

    Thanks to Today I Learned for the tip.

  • Link: Paper Theme Now Supports Full Posts on Homepage

    Amit writes: Paper Theme Now Supports Full Posts on Homepage:

    I have released an upgrade (v1.1) to Paper theme for Micro.blog … It includes a setting now to display full post content on the homepage of the blog.

  • Micro.blog respects min_version in theme.toml

    On 31 March 2022 Manton said:

    Deployed a bunch of server changes today. Some behind-the-scenes stuff that @vincent has been working on, plus fixes to managing themes and pages. Micro.blog now respects min_version in Hugo’s theme.toml file and will show this notice to make it easy to update:

    Screenshot of Hugo version update notice.

  • Export the template files for your theme

    From Today I Learned:

    💁‍♂️ You can access the template files for your theme via export.

    • Go to the web app ->
    • Select the Posts tab ->
    • Select the ... button at the top ->
    • Select Export ->
    • Select Export theme and Markdown .
  • Export theme and Markdown

    I added a new export option to Micro.blog: Posts → … → Export → “Export theme and Markdown”. This gives you a Hugo-structured folder of theme templates, merged in with custom CSS, plug-in templates, and Markdown for any posts. Basically everything except uploaded photos.

  • Link: Scribe Micro.Blog Theme

    Chris Hannah has created Scribe - A New Micro.blog Theme:

    I’m very pleased to announce that I’ve now completed my third Micro.blog theme!

    It’s called Scribe, and it’s my attempt at taking one of my earlier themes, Fortis, as a base. And making it loot a bit more contemporary, with a nice serif font, warm colours, but still maintaining a very readable and clear layout.

  • Link: Hains-Point: A theme for micro.blog

    Hains-Point: A theme for micro.blog:

    A customizable newsletter-focused theme for Micro.blog. Includes featured posts, asides, and more!

    Written for Micro.blog by Jason Dettbarn @endonend.

  • Porting Hugo theme to Micro.blog

    Micro.blog is a blogging platform built over Hugo, a fast static site engine. Given the way it is structured, every theme created for Hugo can potentially work with the blog hosted by Micro.blog. However, there are a few aspects added to Hugo that are specific to the way things work in Micro.blog. These need to be included as part of the themes to make the most of the features of this platform.

    This article presents a non-extensive list of things that should be evaluated and included while porting a theme that is made for Hugo to Micro.blog. I have written this as I dug into the existing themes while porting Paper theme. As of this writing, a theme is considered as a plug-in in Micro.blog. Hence, many references link back to the way plug-ins work with the platform.

    To reiterate, this is not an extensive list. Based on how a theme, that is being ported, is set up, one may need only a few of these steps or may need a few more than those listed below. However, this should be a good start to get a working version of the theme out for testing.


    Of course, the article assumes that you have already identified the theme that you want to port. The Hugo theme Showcase is a good place to check for all the wonderful themes available.

    Though you are not required to have a detailed understanding of Hugo to port a theme, the knowledge on the below aspects should be handy.

    Getting Started

    The first step to get started is to access and clone the repository of the theme to be ported. You can either do this offline on your desktop or directly create a new theme in Micro.blog with mentioning the theme repository URL as Clone URL. You could then select this newly added theme as a custom theme for your test blog. This allows you to find out what breaks and also validate the additional modifications that you make to the theme.

    For a theme to work, you only need a few folders and files — a typical Micro.blog theme directory structure is provided below for reference.

    	├── theme.toml
    	├── config.json
    	├── plugin.json
    	├── layouts
    	└── static
    • theme.toml - Contains bare meta information about the theme, like name, description, license, features, author.
    • config.json - Contains any properties required and referenced by the template files of the theme. If the property is to be provided by the user, typically it should be taken as a setting, defined in a separate file.
    • plugin.json - Contains meta information about the custom theme to be displayed as part of plugin repository. It also defines the feature settings that can be provided by user while plugin configuration. Refer to official guide on plug-ins for more details about this file.
      • layouts - A folder that stores html templates that defines how views of different content types will be rendered on a website with the style.
    • static - A folder that stores all the static content like CSS, JavaScript, etc.

    You can get rid of all the other unnecessary files and folders and only keep the above-mentioned ones. This will keep the list of files in which changes are to be made manageable.

    Before we move ahead, here’s a list of basic template files in the layouts folders that one would modify typically to port a theme.

    • /_default/list.html - A template that renders pages with multiple pieces of content, this includes the homepage. A homepage can also be independently styled by defining a template index.html in the root directory.
    • /_default/single.html or posts/single.html - A template that renders a page for a single post.
    • /_default/list.archivehtml.html - A template that renders the archive page of your website.
    • /partials/head.html - A template that defines the head section of your final rendered HTML.
    • /partials/header.html - A template that defines the header of your blog. This typically includes the site title, subtitle, navigation menu etc.
    • /partials/footer.html - A template that defines the footer of your blog. This typically includes the copyrights, author information etc.
    • /_default/baseof.html - A base template that stitches all the above defined partials together, including the main sections defined in list and single template pages above.

    A theme might have all the above files, or have just a subset of these. In case a theme does not provide a particular template file, one from the basic theme (which forms the base of every theme) of Micro.blog is used.

    Moreover, make sure you configure the appropriate Hugo Version to be used for your blog. Micro.blog allows two versions of Hugo to be used, 0.54 and 0.91, the latest being relatively new. Many themes may not work with the older 0.54 version of the Hugo, typically indicated by the min_version configuration in the theme.toml. If the value is above 0.54, set the Hugo version to be used as 0.91. This can be done via Design → Hugo Version.

    Fix the Broken Pages

    Usually, the home page might not render the list of all the posts with the ported templates. This is often due to the wrong selection of the posts. To check the selection, visit the list template mentioned above and fix the file which is fetching all the posts. It should typically look like below where you pull all the regular pages where type is defined as post.

    	{{ $pages = where .Site.RegularPages "Type" "post" }}

    A similar fix would also need to be applied to the archive page’s template, if it is defined custom. The archive page would also need styling the components appropriately, as these are all Micro.blog specific classes, not part of the default styling of the theme.

    Next, you will have to fix the templates to handle the title-less posts. Most posts published with Micro.blog are, well, micro-posts with no titles. So, wherever a Title is referenced, it should be wrapped in a {{ if .Title }}  condition. So, the title reference at every place should read like below.

    {{ if .Title }}
    	<h2>{{ .Title }}</h2>
    {{ end }}

    The title-less posts might also need minor styling fixes. A typical pitfall is when a post permalink is only available with title. So, a micro-post requires a different element to carry the permalink, mostly the date-time of the post.

    Another aspect that is typically broken is rendering of the taxonomy. Most of the themes in Hugo use tags to define the taxonomy. Micro.blog uses categories and hence need to fetch them differently. So at every place a template mentions tags, mostly on list template, archives template and single template, replace them with categories. This primarily involves replacing all the references of .Params.tags with .Params.categories.

    With these changes handled, you should have a working website that renders correctly. However, it is still not customised to include the benefits that Micro.blog brings to the table.

    Add Micro.blog Specific Tags

    Micro.blog packs the key IndieWeb principles, like IndieAuth, MicroPub, Webmentions, out-of-box for all websites hosted with the platform. However, this does involve defining a few relevant aspects at appropriate places. In addition, the platform is also rich in the ways a user not adept with coding can customise their website to their liking, with support for providing custom CSS, footer and plug-ins. Enabling these also need relevant components to be defined.

    The changes to be made are in two files. First, modify the partials template that defines the head section of your website, /partials/head.html.

    <link rel="stylesheet" href="{{ "custom.css" | relURL }}?{{ .Site.Params.theme_seconds }}">
    <link rel="me" href="https://micro.blog/{{ .Site.Author.username }}" />
    {{ with .Site.Params.twitter_username }}
    	<link rel="me" href="https://twitter.com/{{ . }}" />
    {{ end }}
    {{ with .Site.Params.github_username }}
    	<link rel="me" href="https://github.com/{{ . }}" />
    {{ end }}
    {{ with .Site.Params.instagram_username }}
    	<link rel="me" href="https://instagram.com/{{ . }}" />
    {{ end }}
    <link rel="authorization_endpoint" href="https://micro.blog/indieauth/auth" />
    <link rel="token_endpoint" href="https://micro.blog/indieauth/token" />
    <link rel="micropub" href="https://micro.blog/micropub" />
    <link rel="microsub" href="https://micro.blog/microsub" />
    <link rel="webmention" href="https://micro.blog/webmention" />
    <link rel="subscribe" href="https://micro.blog/users/follow" />
    {{ range .Site.Params.plugins_css }}
    	<link rel="stylesheet" href="{{ . }}" />
    {{ end }}
    {{ range $filename := .Site.Params.plugins_html }}
    	{{ partial $filename $ }}
    {{ end }}

    Next, add the below lines to the end of your base template, /_default/baseof.html just before </body>. These load the custom footer and the plug-ins defined JavaScripts.

    {{ partial "custom_footer.html" . }}
    {{ range .Site.Params.plugins_js }}
    	<script src="{{ . }}"></script>
    {{ end }}

    Display Replies as Conversations

    Micro.blog allows including replies made on the posts to be shown as conversations on a post page via a design setting (Design → Include conversation on post page). However, for the replies to be rendered on your post page, you need to modify your single template, /_default/single.html or posts/single.html, and add the below lines at the end.

    {{ if .Site.Params.include_conversation }}
    	<script type="text/javascript" src="https://micro.blog/conversation.js?url={{ .Permalink }}"></script>
    {{ end }}


    The difficulty involved in porting a Hugo theme to Micro.blog depends completely on the complexity of the original theme. Though it is difficult to extensively cover all the changes required, fixing the things that are broken and adding support for the Micro.blog specific features and tags is all it takes. This article attempted to list down the majority of the identified changes.

    In the future, the way of including the Micro.blog specific changes may be simplified significantly. This article would be updated accordingly to reflect the same. However, the awareness of the changes being done allows one to appreciate the hidden complexity and beauty of the platform that is Micro.blog.

    If you find anything incorrect with the post or want to add anything more for completion, please reply via email addresses to Miraz or me.

    PS: This post is written and contributed by Amit Gawande and is also cross-posted to his website.

  • Cypress and Red Oak themes available as plugins

    Both Cypress and Red Oak are now available as Micro.blog plugins. I’m planning on updating both to work with WordPress 5.9’s new site editing feature in the near future.

  • Adding Custom Menu Items to Your Blog

    Micro.blog has special Pages that you can add to your blog. Custom themes can get the list of menu item names and their URLs by accessing the site variable site.Menus.main. Many themes use the folllowing in there head/header partial:

    {{ with site.Menus.main }}
           {{ range . }}
             <a class="{{ if eq .URL $url }}active{{ end }}" href="{{ .URL }}">
               {{ .Name }}
           {{ end }}
    {{ end }}
  • Improved theme management in Micro.blog

    From Manton on 29 January 2022:

    Improved theme management in Micro.blog today, including disabling previous theme plug-ins when installing a new theme. Makes it faster to try new themes because they don’t need to be uninstalled right away. 🔌

  • Link: the order for how Micro.blog creates your site

    At the Micro.blog Help Center, Plug-in editing changes:

    To help illustrate how Micro.blog processes themes and plug-ins, this is roughly the order for how Micro.blog creates your site (8 steps)

subscribe via RSS

List of Tutorials.

⌘ This site and tutorials before July 2020 were created by Miraz Jordan. ⌘