Found a mistake? Please contact me.

  • Building Micro.blog Custom Themes That Work with Plug-ins

    Assumed audience: Micro.blog users who have written or are interested in writing their own custom theme and are familiar with Hugo/Go Templates or other, similar static site generators.

    With the introduction of plug-ins, it has become much easier to share ways to expand the functionality of a Micro.blog. Users with custom designs should keep these tips in mind to ensure their themes are compatible with all community plug-ins.

    Anatomy of a Plug-in

    Plug-ins provide four components that are common in most Hugo themes.

    1. Static files, such as CSS for styling elements specific to that theme or custom Javascript to add interactivity and interact with external APIs to embed data. See GLightbox.
    2. Partial templates, which for plug-ins are meant to embed content in a page’s <head>. See Twitter Cards.
    3. Custom page templates to add new pages to your Micro.blog site. See Category Cloud.
    4. Shortcodes, which are special partial templates that can be invoked in the content of posts or pages. See Bookshop.

    Plug-ins that use the first three of these components may require some modification to your custom theme to work.

    Static Files and Partials

    In order to include the static files and partial templates in your design, you’ll want to add the following snippet to where you define <head> in your theme:

    &#123;&#123; range .Site.Params.plugins_css }}
     	    <link rel="stylesheet" href="&#123;&#123; . }}" />
    &#123;&#123; end }}
    &#123;&#123; range $filename := .Site.Params.plugins_html }}
         	&#123;&#123; partial $filename $ }}
    &#123;&#123; end }}
    

    You’ll always want

    &#123;&#123; range .Site.Params.plugins_js }}
        <script src="&#123;&#123; . }}"></script>
    &#123;&#123; end }}
    

    probably in the <footer>.

    This code iterates over all the listed parameters in the includes parameter in the plugin.json configuration that each plug-in sets up and ensures the CSS, JS, and partials are all included and rendered in your templates.

    Custom Pages

    Plug-ins that add a new page to your site, like say a page with a wordcloud for blog categories, have to make some assumptions about your Hugo theme. It’s not unusual, especially with older themes, to use something like this in layouts/post/single.html (which is what pages render as in Micro.blog):

    &#123;&#123; partial "header.html" . }}
      <article class = "h-entry">
        &#123;&#123; if .Title }}
          <h2 class = "p-name  post-title">
            <a class = "u-url" href = "&#123;&#123; .Permalink }}">&#123;&#123; .Title }}</a>
          </h2>
        &#123;&#123; end }}
        <time class = "date dt-published" 
              datetime = "&#123;&#123; .Date.Format "January 02, 2006 15:04:05  -0700" }}">
          <a href = "&#123;&#123; .Permalink }}" class = "u-url">
            &#123;&#123; .Date.Format "January 02, 2006 3:04PM" }}
          </a>
        </time>
        <div class = "post-content e-content">
          &#123;&#123; .Content }}
        </div>
       </article>
      &#123;&#123; partial "footer.html" . }}
    

    When creating a new page template as a plug-in author, however, there is no way to know how someone has structured the “frame” of their site and where to put the page content. What if you have a partial for your header, then a partial for navigation, then a partial for featured posts, then a partial for content, then a partial for pagination, then a partial for the page footer? This is not only quite common, but a plug-in author would need to know the names of each of these partials to render a page that fits with your theme.

    New pages assume that you are using a relatively new feature of Hugo– base templates and blocks. I highly recommend reading the documentation, but in essence, Hugo allows you to define the framing of all of your templates in a new layouts/*/baseof.html special template. In that template (which I recommend defining in _default), you can put all the content for your page header, navigation, and footer. What used to be several partials to avoid code duplication can now live in one template.

    In baseof.html, you can define a named block and then your other templates, such as layouts/post/single.html can define the contents of that block. How does this help plug-ins with pages? Micro.blog has largely standardized themes around taking everything that is contained within the <article> element in the example above and replacing it with:

    &#123;&#123; block "main" . }}
    &#123;&#123; end }}
    

    inside the baseof.html template. So your _default/baseof.html might look like this:

    ```html
    &#123;&#123; partial "header.html" . }}
    &#123;&#123; block "main" . }}
    &#123;&#123; end }}
    &#123;&#123; partial "footer.html" . }}
    

    Then your page templates, like post/single.html might look like this:

    &#123;&#123; define "main" }}
      <article class = "h-entry">
        &#123;&#123; if .Title }}
          <h2 class = "p-name  post-title">
            <a class = "u-url" href = "&#123;&#123; .Permalink }}">&#123;&#123; .Title }}</a>
          </h2>
        &#123;&#123; end }}
        <time class = "date dt-published" 
              datetime = "&#123;&#123; .Date.Format "January 02, 2006 15:04:05  -0700" }}">
          <a href = "&#123;&#123; .Permalink }}" class = "u-url">
            &#123;&#123; .Date.Format "January 02, 2006 3:04PM" }}
          </a>
        </time>
        <div class = "post-content e-content">
          &#123;&#123; .Content }}
        </div>
       </article>
    &#123;&#123; end }}
    

    By standardizing on the page contents being in the block named main, plug-in authors can redefine the main block safely for their custom pages, and you can be rest assured that the page will still look like it’s on your blog.

    Hopefully these tips are helpful to custom theme authors who want compatibility with the community contributed plug-ins on Micro.blog.


    Item contributed by Jason Becker.

  • Plugin images

    There’s a couple of things I’ve learnt (feedback from @manton) when making the swarm plugin, is that only svg images are supported. So, make any icons you use an svg, place them in the static folder and also, reference them locally so they don’t use external urls 👍


    Item contributed by David Hall.

  • Link: Developing plug-ins for Micro.blog

    The official word from Manton: Developing plug-ins for Micro.blog:

    Plug-ins are like lightweight Hugo themes. They can provide all the templates needed for a custom theme, or they can provide just a couple templates, overriding any templates in a built-in design on Micro.blog. Micro.blog applies the plug-in templates after the blog’s theme has been set up.

  • Link: The Kiko Micro.blog Theme Refined: "Kiko: System"

    Kahlil Lechelt modified the Kiko theme to use the system font depending on the OS the page is being viewed on. The mod also refined the home page layout.

    Thanks to @Gabz whose post Kiko in the dark? linked to this.

  • Some big changes for this site: teams and plug-ins

    On 06 May 2020 Manton announced Micro.blog for teams: multi-user blogs, so your whole team can write posts on a shared blog.

    And now, Custom.micro.blog, has been upgraded. So, here's an open invite to anyone who feels they can contribute, to contact me at miraz@firstbite.co.nz .

    Also, on 07 July 2020 Manton announced plug-ins for Micro.blog:

    a plug-ins system for Micro.blog that formalizes a lot of the power of Micro.blog themes, but wrapped in a package that is easier to develop and install. Instead of creating a custom theme for your blog and editing the templates yourself, you might be able to find a plug-in that will add the feature. Unlike custom themes, there can also be multiple plug-ins installed for a single blog.

    Since plug-ins are directly relevant to customising a blog I'm hoping to make this site a resource centre for plug-ins and plug-in developers.

    I'm also always looking for more folks to contribute tutorials, how-tos or just links to helpful resources.

    Let's pool our knowledge and make a fabulous resource for anyone wanting to tinker with their Micro.Blog.

    I also need to thank Manton for his generosity in making this site free! 😀

  • Link: Plug-ins for Micro.Blog

    BIG news today — Plug-ins for Micro.Blog:

    Instead of creating a custom theme for your blog and editing the templates yourself, you might be able to find a plug-in that will add the feature. Unlike custom themes, there can also be multiple plug-ins installed for a single blog.

  • Link: Redesigned theme editor for Micro.blog

    Redesigned theme editor for Micro.blog
    MAY 19, 2020

    I’ve redesigned the theme text editor in Micro.blog, adding a preview pane and other improvements. It now features a split view with the template on the left and your web site on the right.

    Source: Manton Reece - Redesigned theme editor for Micro.blog.

List of Tutorials.

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