I’m so excited about all the activity around new plug-ins and themes. However, some of y’all have noticed that the behavior around plug-ins wasn’t really locked down enough before we rolled out these features. So I’ve been working on fixing that.
This week I’ll be updating Micro.blog with a few changes that I think will make developing and editing plug-ins (and overriding templates) more consistent. I want to document them here for plug-in developers to have a chance to chime in if they have any feedback:
Plug-ins installed from the directory will no longer be editable. You don’t want to make changes only to have them erased when a new plug-in version is available.
Plug-ins created from the New Plug-in button will still be editable. This is really for developing a plug-in. When the plug-in is working, I encourage you to register it in the plug-ins directory so that it’s easy to install.
The order of processing themes and plug-ins will change slightly. Full theme plug-ins first, then any custom theme templates can override that, and then finally non-theme plug-ins can add their own templates.
If someone wants to edit a template in a theme plug-in, they need to use a custom theme to override that template. They can pick a template from the plug-in, but Micro.blog will create a copy of it, not edit the plug-in version.
If someone wants to edit a template in a smaller (non-theme) plug-in, there will no longer be a way to do that, because the plug-in will take precedence over a custom theme. They will need to copy the template and uninstall the plug-in.
Let me know if this makes sense! I know there are a lot of moving pieces. If this breaks anything you’re working on, especially let me know.
To help illustrate how Micro.blog processes themes and plug-ins, this is roughly the order for how Micro.blog creates your site:
Create any default templates in the “Blank” design, like index.xml, index.json. list.archivehtml.html, etc. These basic templates are needed for a blog to be functional.
Create a basic config.json, merging in any partial configs from templates in a custom theme and any includes from plug-ins.
Add any standalone Markdown pages like About, Photos, etc.
Add the bookshelves JSON, custom footer, and custom CSS files.
Add templates for a full theme plug-in if one is installed.
Process the custom theme set for the blog, adding or replacing any templates that were provided by “Blank” or the full theme plug-in.
Process any additional, non-theme plug-ins, adding or replacing any templates that were set up previously.
Finally, create the actual blog post Markdown files, run Hugo, etc.
This is precisely how I was thinking the precedence should be set up, theme plugin first, custom theme next and finally the plugin. I think creation of custom theme and plugin workflow is equally important, it needs to be simple to create a custom theme and select a theme plugin as a base for it.
If someone wants to edit a template in a smaller (non-theme) plug-in, there will no longer be a way to do that
That makes me wonder about this last point in the list, though. Why can’t a similar approach be applied to a plug-in? If I want to change something in the plugin, why can a custom template be built with plug-in as base?
We could add that later. Right now Micro.blog just isn’t storing enough information to make overriding a plug-in template possible, unless it’s a theme plug-in.
This is definitely a limitation but maybe it will also encourage smaller plug-ins that can be duplicated as new plug-ins. In other words, instead of trying to change a template in a plug-in, maybe the best solution is just make a new plug-in.
I agree that it is better to encourage people to make their own plug-ins. This way you have your own custom version which makes it easier to keep things separate for changes, fixes, etc.
This should fix problems updating settings. Micro.blog will attempt to merge all the configs together. Also, plug-ins should really use the “fields” feature in plugin.json because then Micro.blog manages the config behind the Settings button. No need for the user to know JSON or how to edit templates.
More kinds of fields would be good. Right now it supports text fields and checkboxes. Maybe the next step is an optional list of possible values for a field for Micro.blog to show.
The first part of these changes has now been deployed! It should be much better. If you see any problems, let me know. (More improvements coming, of course… The changes there should make a big difference, though.)
Overall, these are great changes and help to simplify Micro.blog. Agree with this sentiment:
No need for the user to know JSON or how to edit templates.
However, if we do create a custom template to edit, what happens when the original theme has an update? Do we need to keep a record of any custom changes we make?
Your custom theme will be around with all your changes.
However, if the original theme updates with significant changes in the files you have customized, those won’t show up, as the files you’ve changed in your custom theme have precedence over the original files.
Everything will still work most of the time, but you might miss some new features. You can bring in the original theme’s changes by manually copying them and merging them with your changes.
In some rare cases, there could be a conflict with the changes in your custom themes so that errors occur and there’s trouble building your site. That should be rare, though.
Also, my experience is that themes get updated a lot initially, and, as they mature, updates happen more infrequently and with minor changes. So I wouldn’t be discouraged. Go ahead and create a custom theme.
Exactly what @sod said. It’s also a good reminder when developing new themes that sometimes splitting it into more, smaller templates is the way to go, since it makes it easier to override just what is needed.
Thanks @jsonbecker! Just to be clear on the GitHub sync, you mean editing a template on Micro.blog and having it pushed to GitHub, or an easier way to pull down changes from GitHub without having to re-install? I know we’ve talked about a few things related to this.
Either direction works, although for my money, I’d rather be able to pull from Github my custom theme, not unlike how a plug in can pull from Github. Despite the great work done on previewing design changes, for some combination of what’s in my test blog and the kinds of changes I do, I think my preferred flow long run is locally developing using Hugo, pushing to Github, and then being able to pull that into my theme. There are some complications I haven’t fully run down with things that are MB specific and can cause a local Hugo build to fail, but I figure I will either solve those problems or eventually write plug ins for the MB parts so that I can avoid issues with my own theme.
That being said, if I could “push” versus sync on demand from Micro.blog to GH and create a PR it would be a huge joy.
Overall, my feeling is that for deep theme work, editing within the micro.blog interface is not the best option. The MB interface is great for small tweaks when you’re just customizing a bit, but not my favorite for full on theme development.
I’d add that in particular, my tweaking can often cause lots of builds and queuing (which is good) but the result is a pretty slow feedback loop. And I see a lot of people complaining about things not working where I think they’re just misreading or not reading logs and don’t realize their changes won’t take effect for 3-4 more minutes while two or three builds stacked up as they edited 2 templates + css.
I just realized that my statement here makes me realize I should probably bite the bullet and make my theme a plug-in, but I’m not sure I want to support it/clean it up/advertise it as “good to use” versus it just being where I put whatever I want. It would, however, let me have Github as the source.
Yeah, the advantage to making it a plug-in in the directory is that you can push to GitHub and then you get an “Upgrade” button in Micro.blog, which does mostly what you want for GitHub sync. I don’t think you should feel any pressure to support it. I can see how that might be tricky though if people do ask you questions.
