Add Microformats

[dltj]

This is an enhancement or feature.

Summary

Add microformats to markup

Context

See #3017

[mmistakes]

Overall happy with this PR. I'm not thrilled with adding duplicate markup in _layouts/single.html so if any of that can be removed or DRYed up I'd feel better about it.

But all of the class based markup added looks 💯.

[mmistakes]

Is there a better way of applying microformats for this data? This is the sort of extraneous markup I wanted to avoid, especially since it's duplicating the published/modified datetimes from above along with the authorship that is already being applied the author sidebar.

I get all sorts of "code smells" from it not being DRY and having to hide it all via CSS.

[dltj]

Yes—the repeated variables bother me, too. The driving cause for that is how microformats need the data to be the contents of the enclosing tag and Schema.org puts the data in attributes. Specifically:

microformats do not use link or meta elements within the content of the page and in some cases require particular elements to be used to encode information, such as using abbr to support the datetime-design-pattern as illustrated by the dtstart property in the example above. ("Mixing Syntaxes" heading at W3C's "Mixing HTML Data Formats" page)

I used existing tags where possible (the p-name class for the <h1> article title and the e-content class in the article <section> tag). The contents of the hidden <ul>, though, were the values from the Schema.org <meta> tags.

For a while, I was putting microformat markup in the _includes/page__meta.html, but separating the article microformat data across two template files felt like a worse compromise as compared to keeping all of the HTML data formats in close proximity in one template file.

[mmistakes]

With all of the "hidden" list element items, which are actually required? Can we move forward with the other data you marked up that isn't hidden from view?

I'm still iffy on the duplicating all the author markup as it's in the sidebar with microformat markup now.

Can the published/modified dates be marked up in _includes/page_date.html instead? Neither of those are hidden and you wouldn't have to duplicate the markup then.

[mmistakes]

Careful with your author variables. You start with site.author which will cause problems if someone has assigned an author to the post where it should override the "site" author.

You're also mixing in a {{ author }} variable to do the avatar. They probably should all be {{ author }}. Take a look at how the assign works in the author sidebar to see how I did it there.

A conditional is needed for author.avatar since we can't guarantee someone set an image and wouldn't want an empty <img>.

Either way I question if the author microformat markup is even needed here as you've added it to the sidebar already. Will it fail without it? Just trying to get a feel for how DRY this can be since I'm not really thrilled with all the duplicate markup.

[dltj]

Oh, wow... an excellent point about the mixing of author variables. I will fix that with an update to the branch.

Regarding the author microdata markup in two places. The markup in the sidebar is describing an h-card. In the microformats world, it seems like the site homepage should contain this markup to describe the controlling entity of the site. The author markup in the "_single.html" file covers the stated author of the article on the page for an h-entry. (And that is where I'm definitely misusing {{ site.author }}.

I'm not familiar with the mechanics of multi-author Jekyll blogs, but from what I can gather the site variables are appropriate for the sidebar (the "h-card" microformat covering the entire site) while the author variables are appropriate for the article itself (the "h-entry" microformat).

[dltj]

Please see the updated commit to the PR. I'm using the assigned-author structure now. I found that it does not have an author "URL" defined in it, so I removed that from the markup rather than making the assumption that the blog root is the author's URL. The Microformats crowd would probably strongly prefer that to make explicit the connection between the article author and its "h-card" representation, but it is technically optional. I could also add an author URL to the sample _config.yml, but that seems like overkill for this specialized purpose.

[dltj]

Hmm—the specification is fuzzy ("No properties are explicitly required") and then goes on to say an "h-entry should have the following properties at a minimum for consumers:"

• url
• dt-published (timestamp)

In this latest commit, I moved dt-published to page__date.html as you suggested and removed dt-updated (the if..else markup in page__date.html doesn't distinguish between published and updated when it is rendered to the page). I also removed p-author and p-summary as they aren't in the required subset.

That leaves u-url. Interestingly, there is a {{ page.link}} in _layouts/single.html, but I can't find a condition where page.link would have a value (unless it is expected to come from the page front matter). Unfortunately, u-url is a required data element. Thoughts on how to handle this?

I'm still iffy on the duplicating all the author markup as it's in the sidebar with microformat markup now.

The duplication is necessary so the author information occurs within the enclosing h-entry markup, and the sidebar is outside that markup. But since it isn't required I just removed it.

[mmistakes]

The duplication is necessary so the author information occurs within the enclosing h-entry markup, and the sidebar is outside that markup. But since it isn't required I just removed it.

Now I’m remembering why I wasn’t keen on adding microformats years ago 🤣. It would be so much better if it leveraged other standards especially all this data is already in the head or other schema used in the SEO include.

The page.link variable stuff is for “link” posts so you can’t rely on it. https://mmistakes.github.io/minimal-mistakes/post%20formats/post-link/

Maybe the best path forward is add the bare minimum of microformats that doesn’t duplicate markup. Then let me noodle on future support.

The theme is showing it’s age and a lot of other features being requested could benefit from me doing a complete overhaul. Microformats could be lumped in with that…

[dltj]

Yes, I am disappointed that the IndieWeb folks aren't using something more structured like Schema.org, but I don't have any leverage to steer that community...and it seems like they have quite the organic mix of tool providers that are using microformats.

Are you okay with merging the pull request as it is now? The minimal parts of microformats for Card and Entry have been added to the existing theme markup with the exception of the hidden <ul> list with the one list item for the URL to the post. I could clean up the wording of the list item explaining the hidden list—say, "This list item holds the microformat entry for the link to this post, and it is hidden from view"—and make a final commit to this pull request, if you prefer.

If not, I'm happy maintaining my own fork of mmistakes to get the microformats functionality. (Which is using the organic-mix-of-tools to get Twitter and Facebook conversations onto the blog post entry.)

[mmistakes]

The hidden content still gives me a bad feeling.
In fact was looking at the Microformats wiki and they even discourage it.

If some content doesn't fit into your visible design, then it's not worth microformatting it.

Microformats provide a mechanism for marking up visible content. Any mechanism for embedding invisible or hidden content risks being considered spam due to the fact that invisible (meta)data inevitably ends up being abused. Avoid invisible (meta)data. Publish visible data.

https://microformats.org/wiki/faq#Hidden_Content

[dltj]

You're right: the Microformats wiki does discourage the use of hidden content. That said, I think having something in the markup that points to itself seems to be a pretty critical idea—especially if some machine process is going to extract the data out of the page to make use of somewhere else.

I went poking through the Schema-org markup for CreativeWork, and there is a property from the inherited Thing for URL—and that property isn't used in the mmistakes markup at the moment. Perhaps a permalink can be added to the footer of the article, and that can be marked up with both itemprop="url" (for Schema-org) and class="u-url" (for Microformats).

<p>
  <strong><i class="fas fa-fw fa-bullseye" aria-hidden="true"></i> Permalink:</strong> <span itemprop="url" class="u-url">https://dltj.org/article/dltj-with-webmention/</span>
</p>

If you like, I could wrap it in a Jekyll {% if %} block that checks for a feature flag that is set to "false" by default so the addition doesn't have a visible impact on existing sites.

[mmistakes]

What if instead of adding it to the footer metas... and adding yet another config toggle, you include the permalink in the h1 with the post title? I don't think it harms anything doing that.

<h1 id="page-title" class="page__title" itemprop="headline">
  <a href="{{ page.url | absolute_url }}" class="u-url">{{ page.title | markdownify | remove: "<p>" | remove: "</p>" }}</a>
</h1>

About the only change would be a visual one as the title is now styled like a link... which I don't see any issue with.

[dltj]

Yes, this looks good. I didn't like the styling of the <h1> tag as a link, so I overrode that in the SCSS to make it look as it did before.

How does this PR look to you now? I presume you will squash all of these commits into one merge to master, but if you rather I make a new PR with just one commit with all of the changes, I'm happy to do that.

[mmistakes]

Thanks for the work on this PR. We're really close. Just the small Sass variable change and then replacing out the hidden author URL markup and this will be good to merge.

[mmistakes]

Can we remove this hidden markup since u-url is being applied to the author.home link.
If u-url is required and the thought was to add the hidden markup because there is no guarantee someone adds author.home to their config.

Perhaps we can do a similar thing to the post title. In this case make the author name a link... use author.home first fallback to the site's root URL if the home link hasn't been configured.

<h3 class="author__name" itemprop="name" class="p-name">{{ author.name }}</h3>
  <a class="u-url" rel="me" href="{{ author.home | default: '/' | relative_url }}">{{ author.name }}</a>
</h3>

[mmistakes]

Replace with $text-color variable so each of the skins can assign the correct text color to match. They're not all dark gray.

[dltj]

Ah, yes—moving that hidden markup into the author__name <h3> is a good pattern. Speaking of good patterns, I also applied the same {{ author.home | default: '/' | absolute_url }} construct to the author__avatar block immediately above this code to remove the {% if author.home %} conditional.

$text-color fixed too...that was a midnight mistake.

[mmistakes]

All systems are go!

[dltj]

Many thanks. I appreciate working with you on this.