Microformats That Work

Definition

Most Notes, not unlike tweets, are short-form, titleless status updates.

Title (or name), in this case, means either a p-name class (for h-feed entries) or title tag (for Atom or RSS items).

Typical Example

The markup below is but one example of how a note may be rendered in the context of an h-feed.

Again, actual notes should not have a title. In this case, however, rather than leave out headings altogether, which I’m afraid might not be the most accessible approach, I’ve simply chosen to not add a p-name class (and visually hide the heading using CSS).

<article class="h-entry">
  <h2 class="sr-only">Hello World</h2>
  <div class="p-content">
    Hello world!
  </div>
  <footer>
    <p>Filed under <a href="/category/general" class="p-category" rel="tag">General</a></p>
    <p>On <a class="u-url u-uid" href="/notes/1234" rel="bookmark"><time datetime="2021-06-01T13:00:00+02:00" class="dt-published">June 1, 2021</time></a>
    </p>
    <p>Also on <a href="https://twitter.com/alice/1234" class="u-syndication" rel="syndication">Twitter</a></p>
  </footer>
</article>

Remark: On single-entry views, you’d typically replace the h2 with a h1, and reuse its content in the page’s title tag.

On second thought, dropping the h2 on feed pages is probably not too bad, but not having a clear h1 (or title) is probably problematic (on any page).

Next to a permalink to the note itself (i.e., its single-entry page) and “published” timestamp, this typical example also contains a p-category, and a syndication link marked up with u-syndication.

h-card

Note that I’ve left out a p-author or h-card element. I like to think that adding a single, separate h-card to the overall h-feed instead is good for accessibility. (All of the feed’s entries should—and most parsers act this way—automatically inherit this card.)

On a single-entry page, however, this h-card should be inside the h-entry.

It’s probably best to define your personal h-card as a partial of sorts and have your server-side script or static site generator include it where needed.

RSS Equivalent

<item>
  <dc:creator><![CDATA[Alice]]></dc:creator>
  <description><![CDATA[Hello world!]]></description>
  <category>General</category>
  <pubDate>Tue, 01 Jun 2021 13:00:00+0200</pubDate>
  <link>https://example.org/notes/1234</link>
  <guid>https://example.org/notes/1234</guid>
</item>

Remarks:

• There’s no title element, the RSS equivalent of a missing p-name. (Yes, this is valid RSS!)
• Absolute URLs only. (This is debatable, as most—but not all—feed aggregators will correctly resolve relative URLs. Still, relative URLs are probably bad.)
• It’s not actually necessary to wrap plain text in <![CDATA[]]> tags, but doing so probably helps prevent future mistakes.