Plug-ins

Developing plug-ins for Micro.blog.

Micro.blog plug-ins extend your blog with additional features or customization for themes. Read Manton’s blog post for an introduction.

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.

A plug-in needs to have at least one file — plugin.json — and it can have other files as needed. The plugin.json file describes the plug-in and what parameters or include files it needs.

If a plug-in has a config.json file, that file can have only the parameters a plug-in cares about. Micro.blog will first set up any default parameters, then apply the blog’s theme parameters, and then apply any extra parameters in the plug-ins configured for that blog.

The basic structure of plugin.json looks like this:

{
  "version": "1.0",
  "title": "My plug-in",
  "description": "1-2 sentences about what this plug-in offers.",
  "includes": [
    "/example.css",
    "/example.js",
    "example.html"
  ],
  "fields": [
    {
      "field": "params.photos_use_category",
      "label": "Use category",
      "placeholder": "Enter the category name to include photos from"
    },
    {
      "field": "params.photos_only_microblog",
      "label": "Only include short microblog posts (without a title)",
      "type": "boolean"
    }
  ]
}

Only version, title, and description are required. Micro.blog uses the version number to tell the user that a newer version of the plug-in is available. Version numbers usually start at “1.0” and are incremented like “1.0.1” and “1.0.2” for small bug fixes, “1.1” for new features, and “2.0” for major upgrades.

The includes field is optional. If present, Micro.blog automatically adds link(CSS) or script (JavaScript) tags to the blog. The files references in includes should also be in the plug-in. You can add them as static files under the “static” folder in the plug-in.

For example, if you want to include a CSS file named “hello.css” in your plug-in, it would be stored at “static/hello.css” and referenced in includes with the path “/hello.css”.

If you include an html file, Micro.blog will load it as a Hugo partial. You can add those files in the “layouts/partials” folder in the plug-in. These partials are included inside the head tag of the blog, so they are useful for adding metatags or inline styles and JavaScript.

The fields field is also optional. If present, Micro.blog will build a settings screen for the plug-in. Fields can be of type “string”, “boolean”, or “integer”. For booleans, Micro.blog will use a checkbox. If you need to provide default values, set them in the config.json file.

Fields can override some Hugo variables, or add new parameters that are accessible from the plug-in or any other theme. To add your own parameters, use “params.” as the prefix for your field name.

Plug-ins can be developed and edited inside Micro.blog with the theme editor, so that you can test them before making them available in the plug-in directory for other users. On the Edit Custom Themes screen, click the “New Plug-in” button to get started.

Feels like there was another help article better suited for this info but I didn’t see it so here we go:

I believe the category cloud author updated his/her GitHub name. In any case, the listed link from the find plugins page likely ought to be updated to point here.

Oh, and if y’all know Lukas, I added some plausible analytics functionality to my site that would fit nicely within his plugin. A page not included in navigation for displaying a button to toggle exclusion of visits (necessary for browsers within which one cannot access the JavaScript console). It even worked inside Gluon when I left myself a link via post.

is there any way of injecting HTML code into Body End rather than Head @manton?
I’m trying to adapt Lukas’s Plausible Analytics code to Simple Analytics.
(as a matter of fact, it doesn’t seem to be injecting into https://wa.rner.me at all, even into Head!)

I added in New Plugin in Edit Custom Themes as instructed:

Yes, if you name the template with a “.js” extension instead of “.html”, Micro.blog will include it at the bottom right before the closing “body” tag.

I’ve noticed this doesn’t work with the Cypress theme. I can get that fixed, but it should work most everywhere.

Thanks for prompt response @manton.

In the GH repo, I’ve changed to layouts/partials/sa.js
and updated the reference in plugin.json to sa.js.
(N.b. I changed filename to lowercase incase that was an issue).

Will look for it in Body End. I’m not confident though, because it didn’t even inject into Head before!

Also does it matter that it’s not technically Javascript? It’s technically HTML because the javascript is announced with a tag (also next line a tag which I’m not familiar with).

I’ve now noticed that the M.b plugin didn’t automatically update from the change to GitHub Master branch.


Is it not setup to automatically track GH @manton ?


Adriaan at Simple Analytics suggested to me to put the Javascript in a .js file and the tag (backup for folks who disable Javascript) in a .html file.
So I’ve done that change and re-added the GH repo to https://w4rner-test.micro.blog/ this time.

Let’s see if this one works!

@manton no code is injecting whatsoever!
Can you give me some test code to make a repo of just to check that I can inject a plugin?

My theme absorbed a bunch of plugins. You could browse the partials to see where stuff gets injected. You can compare it to @manton’s marfa theme as I built off that. I may poke around when I wake up a bit and help you out directly. My theme lives here: https://github.com/moonbuck/theme-moondeer

It is still highly hardcode tailored for my needa’s so I wouldn’t recommend anyone installing it … but a lot of hugo stuff happening in the code.

Side note: now that I know how everything works I may offload the absorbed plugins and try parameterizing enough things to make it (and perhaps a shortcode library or something) publicly useful.

Update: In fact, I just piddled around with refactoring my modification of @lukas’s plugin (https://github.com/LukasRos/plugin-plausible) out of my theme and into a separate plugin (https://github.com/moonbuck/plugin-plausible-plus) and it seems to have worked as intended. The only thing different in my plugin is the addition of a page that lets you toggle the exclusion of visits.



Huh: maybe I should try to just change one thing.
Mind sharing what it looks like on the M.b design tab side? Feel free to DM w@ rner.me

I just dropped the README into a new topic. See if this helps.

I guess since this is the official plugins topic I oughta list all the new plugins. Dissecting my theme gave me plugins for days:

plugin-bookshelves
plugin-cards
plugin-category-cloud
plugin-plausible-plus
plugin-prismjs
plugin-banner
plugin-lightbox
plugin-gallery

That’s great! I’ll get the rest of these added to the plug-in directory so they’re easy to discover for people.

1 Like

plugin-favicons should be good to go. I have a few more but they still need READMEs.