Extract common Micro.blog head elements and make them compatible with Hugo 0.117

[svendahlstrand]

As the title suggests, this pull request extracts common Micro.blog head elements into a partial and makes sure that they are compatible with Hugo 0.117.

I extracted the Micro.blog specific head elements from the Marfa theme and then glanced over the other official themes to look for discrepancies. So there's a companion pull request in the theme-marfa repository where all the common elements are replaced by the inclusion of the partial introduced here.

Okay, onward to some notes on changes and potential problems…

Potential "breaking" stuff affecting all themes

Until now, the podcast feed was always present in head, even if there were no episodes published. I've changed that behavior to only include the feed when there is at least one episode published.

Also, I added a missing reference to the podcast.json file.

Today, when one visits a category page like https://www.manton.org/categories/coffee/ the head includes a reference to the corresponding RSS feed, as one might expect. The JSON feed, however, points to the main feed ("home feed"). This pull request changes that.

Speaking about podcast feeds, the layouts use different ways to identify podcast posts. The JSON version uses .Params.audio while the RSS version uses .Params.audio_with_metadata. Is this intentional, @manton, or should we change this?

The EditURI link element is now always present. Previously, it was only there if there was an RSS feed present in the head. On the homepage and category pages, for example, but not on other pages.

I removed the reference to .RSSLink (that no longer exist) to get blogs building on Hugo 0.117.

Potential "breaking" stuff in some themes

Today, the custom stylesheet is cache busted only in some themes. With this pull request, it will always be busted using {{ .Site.Params.theme_seconds }}. Let me know if this is what you want, @manton.

On the subject of stylesheets, it's worth thinking about cascading and the order of elements in the partial.

As most of the stuff in the common Micro.blog head is metadata, how we order the HTML is mostly a question of taste. With a few exceptions: custom.css, CSS files provided by plug-ins, and HTML provided by plug-ins. I've kept the order from the Marfa theme: custom.css first, followed by plug-in CSS files and then plug-in HTML.

Some themes might potentially include this stuff in another order today, but the ones I've checked look okay.

Where each theme chooses to include the microblog-head.html partial will also matter. I guess including it right before </head> makes the most sense. That will make it likely that custom.css is included and applied after theme-specific styling.

Category feeds and taxonomies

Let's talk about categories and feeds. The documentation only mentions one such feed:

https://username.micro.blog/categories/my-category/feed.xml – Posts from a specific category on a blog.

Nice, this works. Here's a real-world example: https://www.manton.org/categories/coffee/feed.xml.

There's no mention of a JSON feed, but looking at the default config.json, we see it's intended that such a feed should exist. It doesn't, however. Fetching:

https://www.manton.org/categories/coffee/feed.json

returns a 404. That's because there was no layout available to handle it. From Hugo's build log:

WARN found no layout file for "json" for kind "taxonomy": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.

But now there is! So, the example above works with this pull request. As does:

https://www.manton.org/categories/feed.xml
https://www.manton.org/categories/feed.json

to get a list of categories in feed format. The RSS variant was already working, but not the JSON one because of the missing layout file.

Maybe you didn't indent for all these different feeds to exist, @manton, and if that's the case, I can revert the relevant commits and change config.json to match the output formats you want to be available.

I also removed the depracted taxonomyTerm from config.json.

What now?

Here's how I suggest we go from here.

1. I would love to get some feedback on this pull request. Am I on the right track? Something missing? Or is there anything that should not be here? Is microblog-head.html good or should we name the partial differently?
2. I make changes based on the feedback.
3. We make Marfa use this new partial and roll it out to production.
4. When we are reasonably sure I didn't break anything, I will go forth and update the rest of the built-in themes.
5. We let third-party developers know that this partial is a thing and that they should use it for their convenience and future Micro.blog compatibility.

[manton]

On first glance this looks excellent. Will dive in more later… I'm especially glad that the category JSON Feed works now. I always meant to revisit that and make it work.

[manton]

I agree with all of these changes. Thanks very much @svendahlstrand. For consistency, I like moving to .Params.audio_with_metadata even if we're not currently using the extra metadata.

I'm also good with the name microblog-head.html. I wish I had named custom.css something like microblog-custom.css… Probably shouldn't changed that right now, but we could consider it later (and support both filenames for a while).

[manton]

Forgot to add… I also agree about where to place the include (right before </head>). Most importantly, we should document in a help page how things will cascade if there are multiple plug-ins and custom CSS.

[jsonbecker]

I basically did this for myself when making my own theme. I basically scoured Marfa for things missing in my old Hugo theme and added it bit by bit to make Micro.blog feature work.

I think that this is worthwhile mostly so that folks can far more easily bring new Hugo themes in.

Just add this partial to get the MB-specific sauce that gets you to 99% working in every Hugo theme.

One thing that is tangentially related to this is some documentation and/or clearer standards (possibly through a partial?) of things like “where do you get the list of things that Micro.blog calls pages?” I remember integrating that with my custom menu took some digging.

So this is a comment in support of this change and any other that better encapsulates the added magic needed to just drop any Hugo theme into MB. The sort of “merge/coalesce” with defaults for templates and configurations help. More of that!!

[MattSLangford]

I'm fully on board with this. Any intention to include things like OpenGraph? Or just leaving it for the Micro.blog specific things? (Full Disclosure: Just got back from a trip and have only looked at this for a few moments.)

Edit: See new comment ↓

[MattSLangford]

Alright, had some more time to look this over. When making Tiny Theme, I basically did the same as @jsonbecker. I also looked at other themes (and plugins) to try to cover all bases. I pieced together things from Marfa, a couple other themes, and added some stuff of my own.

This is one of those things where a standardized order/format makes perfect sense. I would absolutely use this as the default. Would help with future proofing, tech supporting, and so much more.

I could even see it including basic title/description and opengraph support.

And one minor thing: Might as well change that twitter.com to x.com while making changes.

[svendahlstrand]

Thanks, @jsonbecker and @MattSLangford for taking the time to review this change. I'm happy you find this a good idea.

About Open Graph, title, description, and other common head elements; it makes sense to extract those as well. But maybe they should be in a different partial, like common-head.html or similar. I can see theme and plug-in developers having different ideas of how to construct a title or how to source Open Graph data. If these elements are tangled together with required Micro.blog elements, the only way to override them is to copy-and-paste the content from microblog-head.html and make the relevant changes. And by then, we lose the benefits of having a single truth, with future proofing, and so on.

I think the markup in microblog-head.html should be kept to the strictly necessary and required Micro.blog stuff. In other words, a third-party developer should never want to touch that file; just include it to make their theme Micro.blog compatible. But this is just me thinking out loud. 😊 @manton might have other ideas.

When it comes to X, that's one of those changes that may look like a minor thing on the surface, but is actually quite complicated. I searched the web client repository just now, and Twitter is mentioned 363 times across 97 files. And then there are the other repositories, for the iOS and Android apps, for example. Even if we restrict ourselves to changing the name in user-facing places like labels, descriptions, and documentation, there's a lot of work. I'm not opposed to the change, but I think it should be a project on its own, separate from this change. Or maybe we'll just wait for a while and see what happens with twttr Twitter X. 😅

[jsonbecker]

I have a section in my own head that just does this:

{{- template "_internal/schema.html" . -}}
{{- template "_internal/opengraph.html" . -}}
{{- template "_internal/twitter_cards.html" . -}}

admittedly, there may be more useful stuff in Hugo now. But I never understood what people who weren't specifically trying to set values for OG wanted past the built into-Hugo templates.

[MattSLangford]

@sod - I understand your point about OpenGraph. I also like your idea about having it as a separate partial. I think stuff like that would be hugely beneficial for people wanting to build a theme. It would make it very easy to have a starter template of sorts that includes functioning tags and data.

[am1t]

@svendahlstrand I am completely on board with all these changes -- most of my themes already have a separate microblog-head of sorts. I would gladly replace that with a common head.

But how do you set the base theme to blank anymore? It's not available as part of the plugins list. So if someone (like me) is using a custom theme, there's no way to get rid of an old theme from the plugins. @manton

[svendahlstrand]

It would make it very easy to have a starter template of sorts that includes functioning tags and data.

Maybe this is the key: instead of having multiple partials with nice-to-haves and optional features, offer a good starter template that uses microblog-head.html and comes with other sound defaults (like including the built-in Hugo features for Open Graph @jsonbecker mentions).

But how do you set the base theme to blank anymore?

That's not really necessary; the blank theme (this repository) is always there. It's not optional. If you want to work from an (almost) blank slate, instead of customizing an existing theme, you will want to create a new theme of your own and choose that as your selected theme.

[manton]

I agree with @svendahlstrand's point that microblog-head.html should be focused on the required stuff for blogs to work. OpenGraph makes sense as a separate partial to me. Maybe just microblog-opengraph.html? That would still feel pretty clean to me. All the built-in themes should probably include both, but other plug-ins could choose to have their own.

[svendahlstrand]

I've updated this pull request with a new commit that uses .Params.audio_with_metadata everywhere. Let me know if there's something else you want changed or added, @manton.

[cdevroe]

👏 @svendahlstrand for kick starting this initiative.

(I'm unsure if this is the best place to have this discussion, if so, I'm sorry.)

Admittedly I haven't updated my Micro.blog themes in a long time. When I was building them I remember having to bug @manton constantly via email to get something to work. In part because the documentation and tooling was so new or nonexistent, and also in part due to my naiveté with Hugo-like platforms like M.b. So I've sort of let them be. Thanks again to Manton for allowing me to pester him!

For Red Oak and Cypress, I'd like to turn over ownership to either the Micro.blog team or anyone in the community that would like to take them over. I believe some sites on M.b find them useful. However, if @manton sees that no one is using them anymore perhaps I'll remove the repos since they are likely very far out of date both in terms of M.b best practices and in CSS/JS etc.

(If someone wants to create a PR on their repos to support what @svendahlstrand is suggesting here, please do!)

[manton]

Thanks for your early work on those themes @cdevroe! I'd love to see those themes continue. If someone wants to take them over, I can transfer the "ownership" in Micro.blog's plug-in directory to the new maintainer. If no one volunteers, I can move them to Micro.blog's GitHub account too.

As a sidenote, when I remember I've been trying to fork plug-ins so there is an extra copy. Because Micro.blog relies on the GitHub repository being online, things are a little more fragile than they probably should be.

[manton]

I'm merging this in. I like the OpenGraph discussion too, but that can be handled separately.

[manton]

This change has been deployed (+ the rename to microblog_head.html).

[MattSLangford]

Awesome. I've already added it to Tiny Theme. Once mb refreshes the plugins, it'll be available. Thanks @svendahlstrand and @manton for the work!

[svendahlstrand]

That's some quick work there, @MattSLangford! 👏