tilde-site/content/blog/2022-12-13-beginner-hcard-h...

164 lines
6.8 KiB
Markdown

+++
title = "A beginner h-card and h-entry usage"
date = "2022-12-13T20:05:00Z"
updated = "2022-12-13T20:05:00Z"
[extra]
authors = ["Ydreniv"]
+++
I've just got started on discovering what [Indieweb](https://indieweb.org/) is.
I've been making static sites for years now, and I've always been interested
in "small-scale web".
Thus, it was only natural that I got into IndieWeb.
I won't go into too much details about this initiative.
I'm still only a beginner, and you will have more accurate information looking
at their website.
But it's basically a set of tools and practices to build a decentralized
version of the web, far from the big social media.
The specificity, compared to what one could simply do with a classic static
sites, is adding ways to interact and understand content.
I will cover interaction in another blog post.
Today, I want to focus on microformats, and especially `h-card` and `h-entry`.
In <a href="https://brainshit.fr/read/326" lang="fr">Une tranche de console
dans Internet Explorer 8</a>, [lucidiot](https://tilde.town/~lucidiot) talked
about WebSlices, and introduced for the first time the notion of [microformats](https://microformats.org) to me.
Later on, while browsing some IndieWeb stuff, microformats appeared once
again.
That's why, on one chilly winter night, I began to try harness this mysterious
knowledge.
However I didn't know where to really start.
I first read the [IndieWeb Getting Started](https://indieweb.org/Getting_Started), then tried [Indie Webify](https://indiewebify.me).
The latter is a linear and interactive introduction.
The sequential steps are great at progressively introducing new notions.
With the help of the [IndieWeb wiki](https://indieweb.org/) and the
[Microformats wiki](https://microformats.org/wiki/Main_Page), I've been able to
get going.
## h-card
So I've started implementing `h-card` on this website.
This is a static site, generated using [Zola](https://www.getzola.org/).
I won't teach you all about Zola.
Basically, you can right Markdown content, which will then be formatted using
templated HTML.
While I use a different template for each page, they all use a `base.html`
template, to put in the basic structure (`head` block for instance).
Thus, I simply included a `include/h-card.html` in this base template.
The `h-card` template is fairly simple :
```html
<div class="h-card hidden">
<span class="p-name">Ydreniv</span>
<span class="p-nickname">masuksa, Ombre</span>
<a class="u-url" rel="me" href="https://tilde.town/~ydreniv">Homepage</a>
<a class="u-url" rel="me" href="https://minis.kestrels-and-roses.rocks">Minis Blog</a>
<a class="u-url" rel="me" href="https://masuksa.github.io/blog">I Am The Fog In The Forest</a>
<a href="{{ config.base_url }}/mg-key.asc" rel="pgpkey authn">PGP Key</a>
<time class="dt-bday">2022-10-26</time>
</div>
```
The `hidden` class just means there is a `display: none` associated with the
block in my CSS file.
It's not necessary, and some people show these informations on their website,
but I felt they were mostly redundant.
As for the `h-card` itself, it is simply added with a `h-card` class on a
block.
Then, classes are added to various elements in the block to specify the
`h-card` attributes.
A full list of attributes can be found in the
[documentation](https://microformats.org/wiki/h-card).
Here, I have a `p-name` to list my name, and nicknames in `p-nickname`.
I've put some urls to my websites.
The fact that they are urls useful to the `hCard` is shown with the class
`u-url`.
And since these various links represent sites of mine, I've added a
`rel="me"`.
This is an attribute used in authentication on the IndieWeb, and thus is quite
important.
I will talk a bit more about it in the Webmention article.
I've also added a public GPG key, which can also be used in authentication.
And lastly is my birthday here, with the appropriate class : `dt-bday`.
There are many more attributes I could have used, but for various reasons,
decided to leave out.
The most important ones are `p-name` and `u-url` anyway.
While this simple block doesn't seem like much, it provides the basic
information for IndieWeb apps to use.
Moreover, it can help you sort out your various online presences.
# h-entry
The second microformat I've tackled is `h-entry`
Here, I went into my `blog.html` template.
```html
<article class="h-entry">
<header>
<h1 class="p-name">
<a class="u-url" href="{{ page.permalink }}">{{ page.title }}</a>
</h1>
<p><time class="dt-published">{{ page.date }}</time>, by {{ authors_macros::authors_inline(authors=page.extra.authors) }}</p>
{% if page.updated != page.date -%}
<p>This article has been edited on <time class="dt-updated">{{ page.updated }}</time>.</p>
{% endif %}
</header>
<section class="e-content">
{{ page.content | safe }}
</section>
</article>
```
I'm using a macro to generate the author field. I've shown it below, but this
simply outputs the author name as a link, with some `hCard` classes to give a
couple information about the author.
As I'm the only one writing articles here, this is a bit overkill, but if
people ever publish articles on this blog, at least I'll be able to let them
do easily.
```html
{% macro authors_inline(authors) %}
{% set authors_infos = load_data(path="authors.yaml") %}
{% for author in authors %}
{% for author_infos in authors_infos.authors %}
{% if author_infos.name == author %}
{% set_global author = author_infos %}
{% endif %}
{% endfor %}
<span class="h-card u-author"><a class="u-url p-name" href="{{ author.url }}">{{ author.name }}</a></span>
{% endfor %}
{% endmacro authors_inline %}
```
There are a lot more Zola templating stuff involved here.
I believe you can however understand or ignor most of it, but wanted to include
it if someone having a go at Zola wanted some example.
Like the `h-card`, everything is in a `h-entry` block.
I then use several classes for the different attributes :
* `p-name` : Name of the entry, here a post title. Entries could be used for
other kind of contents. `p-name` is also used in other microformats,
including `h-product` or `h-recipe`.
* `u-url` indicates a URL.
* `dt-published` : Publication date
* `dt-updated` : Last update. This will appear optionally, if the article has
been updated.
* `e-content` : Body of the article.
## Wrap-up
On Tilde Town, you can always access the (non-compilated) sources in
`/home/ydreniv/tilde-site`.
Feel free to browse it if you want to know more, or if you read this in the
far future, what changes I did bring.
I'll be working on a Webmention article for later. It will probably be split
in halves.
I would talk first about the basic manual setup, then write about how one can
automate things.
Oh, and lastly, a disclaimer : I'm quite new to IndieWeb, so I may be mistaken
on some things.
Feel free to contact me if you want to inform me on the subject.