DEV Community: Kristof Zerbe

Mentions United, GitHub & GraphQL

Kristof Zerbe — Sun, 09 Nov 2025 16:04:05 +0000

A few months ago, in my post Using GitHub as Commenting Platform, 2025 Edition, I explained how GitHub Issues can be used quite easily as a commenting platform:

Create a GitHub issue for each post that contains at least the post URL
Add a syndication link to the issue on the post page
Let Brid.gy and Webmention.io do their job
Integrate Mentions United into the page to display comments via the Provider Plugin Webmentions

So I've made it a habit to syndicate every new post in a GitHub issue. This saves me from having to set up my own spam-proof comment system, which is difficult or even impossible to implement on SSG sites anyway.

One might argue that the data chain Site → GitHub → brid.gy → webmention.io → Site is quite long and offers a lot of room for errors, but all I can say to that is: Yes, you're right, because that's exactly the case at the moment!

A blog like this, with two or three posts a month (if there's time), isn't exactly flooded with comments, so some time passed before I noticed that brid.gy is still polling my GitHub account, but unfortunately isn't getting any results and therefore isn't passing along any web mentions for GitHub issue comments. The chain has been broken!
I will certainly inform the creator Ryan Barrett about this, but that doesn't help me at the moment, so I decided to build a native GitHub provider plugin for Mentions United.

Mentions United: Peertube Provider

Kristof Zerbe — Sat, 03 May 2025 16:52:12 +0000

I don't often work with videos, especially not on social media. But every now and then I record one with my smartphone, for example at a concert or a soccer match, and want to blog about the event later. I then embed the MP4 files as an asset in the corresponding Markdown. Over the years, a few MB have accumulated and at some point I had to think about where to put them in order to keep the size of the blog under 1GB. Outsourcing to YouTube? I can, but that would be the wrong direction for me. Something on Fediverse or the social web? Of course ... Peertube!

On the German instance clip.place operated by adminForge, a channel for the videos was quickly created and uploaded. Basically I only had to change the URL's in the video and iframe tags to the new ones.

I don't expect a lot of comments on my videos on clip.place, as I currently use it more as a repository or syndication target, but you never know ... and since I have so far added a Mentions United Provider Plugin to all of my connected platforms that have a free API, one is now also available for Peertube.

As always, the data for the plugin, i.e. the video URLs, are in the frontmatter of my post. Here is an example of my concert post WIRTZ DNA-Tour 2024, Leipzig @ 2024-02-17:

syndication:
  - host: Peertube
    url: https://clip.place/w/quf3PWpmKJjRwm89axBLY2

In the EJS template for my posts, it is checked whether there is at least one Peertube syndication for the current post and if so, the Peertube provider plugin is integrated and initialized after the main Mention United script in the JS code. Finally, the retrieve method contained in the plugin is called via the general Mentions United load and the comments are displayed on the page, if there are any.

let synPeertube = syndications?.filter(s => s.host.toLowerCase() === "peertube");

<% if (synPeertube?.length > 0) { %>
<%- js('js/mentions-united-provider_peertube.js'); %>
<% } %>

<script>
  ...
  const mentionsUnited = new MentionsUnited({ ... });

  <% synPeertube?.forEach(syn => { %>
  mentionsUnited.register(new MentionsUnitedProvider_Peertube({ 
    syndicationUrl: "<%- syn.url %>",
    syndicationTitle: "<%- syn.title %>"
  }));
  <% }); %>

  ...
  mentionsUnited.load()
    .then(() => { 
      return mentionsUnited.show(); 
    })
</script>

Actually, everything is the same as always, but the Peertube API still has a special feature: although there is an open RESTful API, there are no fixed auth tokens that could be generated in the account UI, for example. Instead, you first have to retrieve the client tokens via the API in order to generate an auth token valid for 24 hours, also via a REST endpoint. A little cumbersome, but you can also retrieve the comments of a video via a token-free Video Feed API JSON format and limit the amount of data with a parameter for the video ID:

/feeds/video-comments.json?videoId={{ID}}

Unfortunately, this procedure has a small catch: In contrast to the REST API, the feed does not provide the complete author data of the comment, but only the display name and the profile URL:

"author": {
  "name": "Kristof Zerbe",
  "url": "https://clip.place/accounts/kiko"
}

Thankfully, the REST endpoint /api/v1/accounts does not require an auth token and so I collect all unique authors in the Peertube Provider plugin, cut the name from the profile URL and use it to retrieve the complete data separately. For example:

{
  "url": "https://clip.place/accounts/kiko",
  "name": "kiko",
  "host": "clip.place",
  "avatars": [
    {
      "width": 48,
      "path": "/lazy-static/avatars/e0891432-0f45-48c5-86c0-594a395f3d91.png",
      "fileUrl": "https://clip.place/lazy-static/avatars/e0891432-0f45-48c5-86c0-594a395f3d91.png",
      "createdAt": "2025-04-01T06:16:21.893Z",
      "updatedAt": "2025-04-01T06:16:21.893Z"
    },
    { "width": 120, ... }
    { "width": 600, ... },
    { "width": 1500, ... }
  ],
  "id": 17957,
  "hostRedundancyAllowed": false,
  "followingCount": 0,
  "followersCount": 0,
  "createdAt": "2025-03-31T07:15:05.857Z",
  "displayName": "Kristof Zerbe",
  "description": "https://kiko.io",
  "updatedAt": "2025-04-01T06:10:52.234Z",
  "userId": 213
}

I mainly focused on the avatar URL, because a small picture of the commenter is a standard for Mentions United interactions and I don't want to deviate from this.

Of course, the number of additional requests for many comments increases significantly with this approach, but I have already opened an Issue (#6998) for this in the GitHub project. Let's see when I can remove the account retrieval again.

Here's an example I used to test the new Peertube Provider plugin: https://kiko.io/post/WIRTZ-DNA-Tour-2024-Leipzig-2024-02-17/#interactions

Original post on kiko.io: https://kiko.io/post/Mentions-United-Peertube-Provider/

Reusable API proxy in just a few lines of JavaScript

Kristof Zerbe — Sun, 27 Apr 2025 11:31:54 +0000

For my project Mentions United, which collects interactions from various platforms via API to display them on the own page, at some point I needed a way to hide the authentication tokens required for some APIs from being used by unauthorized parties. You simply don't leave your security keys lying around in the code, especially not if it's publicly visible on GitHub. This may still work somehow for server languages, but JavaScript (and my solution is based on this) is downloaded in the browser and can then be viewed freely. Obfuscators are useless here, as they have become obsolete in the age of AI anyway.

The only way to do this is to build a translator that takes a request without a token and sends one with a token to the remote site and simply passes the result along. A proxy.

The aim of the solution was basically to replace the URL of an API call with that of the proxy and to leave the other components of the URL as they are, so that, for example, call

https://myproxy.domain/example/api/v1/statuses/12345

becomes

https://example.com/api/v1/statuses/12345

The basis of my small API proxy is the NPM package http-proxy-middleware from Steven Chim, which I utilized to build a system that can be used via configuration for various endpoints and that runs on a server under the Node.js framework Express.

It was also important to me that not just anyone can use the proxy, but only call sources authorized by me, which was quite easy to achieve using the CORS middleware from Express.

Configuration

The data required for the proxy is stored completely in environment variables. PORT (under which port number is the server accessible) and LOG (console output of a proxy process: True/False) are optional and have default values.

CORS_URLS is a comma-separated list of all authorized sources of a request, such as https://kiko.io,http://localhost:4000.

PROVIDERS is also a comma-separated list with the names of the supported API endpoints, such as pixelfed,mastodon,peertube.

For each of these providers, two further environment variables are then required for the base URL and the token value and which begins with the provider name. Example:

MASTODON_API_BASEURL=https://indieweb.social
MASTODON_API_TOKEN=ABC123DEF456

Code

Here is the content of app.js, in the order in which it will be called:

Import of the required libraries:

import dotenv from "dotenv";
import express from "express";
import cors from "cors";
import { createProxyMiddleware } from 'http-proxy-middleware';

Initializing the dotenv library for reading the environment variables and setting defaults:

dotenv.config();

const PORT = process.env.PORT || 3000;
const LOG = process.env.LOG || false;

Initializing the Express Server and the CORS middleware:

const app = express();

app.use(cors({
  origin: process.env.CORS_URLS.split(","),
  optionsSuccessStatus: 200
}));

Creation of a proxy as a reusable function that does the actual work by rewriting the URL of the incoming request using pathRewrite and forwarding it to the target:

function getProxy(provider) {
  return createProxyMiddleware({
    target: process.env[provider.toUpperCase() + "_API_BASEURL"],
    changeOrigin: true,
    pathRewrite: (path, req) => {
      if (LOG) { console.log("Proxying " + process.env[provider.toUpperCase() + "_API_BASEURL"] + path); }
      return path.replace("/" + provider, "");
    },

    headers: { Authorization: "Bearer " + process.env[provider.toUpperCase() + "_API_TOKEN"] }
  });
}

Iterating over all providers and adding the respective proxy to the routing:

for (const provider of process.env.PROVIDERS.split(",")) {
  app.use("/" + provider, getProxy(provider));
}

Starting the fully configured Express Server:

app.listen(PORT, () => {
  console.log(`API Proxy listening on port ${PORT} for ${process.env.PROVIDERS}`);
});

This is it. That's all the code you need for the universal API proxy.

Hosting

The app can be hosted wherever Node.JS apps are supported. I opted for Railway because it allows you to integrate and control a project completely via GitHub. All you have to do is define a source repository and Railway takes care of the build and deployment itself. This reduces the deployment of the proxy server to checking in code changes on GitHub or changing an environment variable via the Railway interface. However, you can also use Deploy GitHub Actions to Railway.

My current railway plan is the Hobby Plan, which is free up to 5$ consumption of resources in terms of memory, CPU and egress (outgoing traffic). At the moment I barely get to 1$ in a month.

GitHub - kristofzerbe/Mentions-United-API-Proxy

See the original post on kiko.io: https://kiko.io/post/Reusable-API-proxy-in-just-a-few-lines-of-JavaScript/

Mentions United ... 3, 2, 1, Go

Kristof Zerbe — Fri, 04 Oct 2024 10:53:22 +0000

Blogging means putting your own opinion on public display, and of course you hope for reactions to it, otherwise you would rather write your thoughts in a small notebook and hide it in your bedside table. Blog posts are therefore always only the first half of a conversation with fellow human beings, readers, and web users. The other half is made up of reactions or, better yet, interactions. Likes, comments, or links from other bloggers who take up the opinion in their own blog post in order to spread it further or discuss it. A story emerges from these two halves.

It seems that blogging is becoming more popular again. After many years of being fenced in by large “opinion corporations”, which made it easy to share information, many people have realized that this simplicity comes at a price, because the opinion itself or even the person was never the focus of interest. The content at the center of the closed networks is monetized or used to manipulate others. Today, blogging is also an expression of the desire for freedom and independence and emancipation from the large social media platforms.

However, this freedom also means that you have to have a fair amount of technical understanding and that linking content is not as easy as on the big platforms, where you just have to be able to use a keyboard. Blogging platforms like Wordpress are certainly a help at this point, but at the end of the day you just have a blog in which you can write down and publish your thoughts in the form of posts, but not automatically a conversation. The most important building block for a real conversation via a blog is the hyperlink, the central element of the World Wide Web. And in contrast to the 2000s, the early days of blogging, today there are a number of ways to communicate via a link and thus to engage in an interaction that goes beyond simply commenting on a blog post.

Interactions

An example: Alice writes a post on her blog...

Bob reads it and writes about the topic in his blog, mentioning Alice's post via its URL.
Alice posts the URL to her post including the headline on a social web platform like Mastodon. Chris reads the post and puts a Like
Daniel replies to and reposts the Mastodon post at the same time
Alice syndicates the complete post, including the URL to the original, on a developer platform such as DEV and Eric comments on this post

All of the above interactions originate on Alice's blog, but they take place outside of her system and are not reflected in the original post. Bob would certainly find Eric's comment or Daniel's reply interesting, but he is just as unaware of them as Alice is of Bob's mention on his blog. A list of all interactions from the web is missing at the original post.

The techniques to accomplish all this already exist. They just need to be put into practice:

on 1: Bob sends a webmention to the endpoint linked by Alice on the post page (e.g. webmention.io) and Alice retrieves it there via the API
on 2 and 3: Alice has previously set up brid.gy to also deliver Mastodon interactions to the Webmention endpoint
on 4: Alice retrieves the DEV comments via the dedicated API

The interactions from the social web aka Fediverse can already be seen on various blog posts today. They are usually pulled directly from Mastodon's API onto the page. However, this usually neglects one important aspect: the linking of the self-performed syndication on the original post, in order to give readers the opportunity to land on an interaction option with just one click!

But how does Alice get the interactions on her page without having to familiarize herself with the respective API's?

She simply uses the client scripts of the Mentions United project ...

Impetus

Three years ago, I not only introduced Webmentions on this blog and wrote about them here and here, but I also started systematically recording my manual syndications on other platforms and displaying them under the post.
I syndicate text posts on Mastodon and, if the content is suitable, on DEV and photos on Pixelfed, Flickr and a few other (unfortunately) closed platforms. I collected all Webmentions and interactions from Mastodon and Flickr using a combination of Aaron Parecki's webmention.io and Ryan Barrett's brid.gy and brought them to the post page using a client-side JavaScript.

But what was always missing were interactions from other platforms. brid.gy could, in principle, collect likes and comments from Pixelfed, the largest photo platform on the social web, but a few bugs that have been known about for four years on the platform prevent this.

Now, I'm not the most patient person, and since there was no response even after repeated inquiries in the Pixelfed issue, and it would only have solved one problem for me anyway, I thought to myself: then I'll just build something myself that is able to pick up interactions from all possible APIs and insert them into my post pages.

Project «Mentions United»

As Robb Knight said about his EchoFeed:

Naming things is hard, leave me alone.

The functionality and structure of the solution were easier to define. On the one hand, it was to be a pure client JavaScript application that runs in the browser on the page to ensure that the data is always up to date and that withdrawn interactions are not taken into account. On the other hand, a plugin system should only ever execute the scripts that are needed.

The project therefore consists of a main script of only 7 KB and two types of plug-in scripts:

Provider plugins to retrieve person-related interaction data and put it into a common form
Renderer plugins to transform the collected data into HTML and insert it into the page

The main script (mentions-united.js) implements following relevant methods:

register(plugin) - Registers a plugin script for execution
load() - Executes the retrieve() method in all registered provider plugins, which collects the data from the respective APIs
show() - Executes the render(interactions) method in all registered renderer plugins, which converts the merged data into HTML and inserts it

Further explanations of how the solution is structured can be found in the README of the GitHub repo.

Available plugins

The initially developed plugins naturally cover my needs for this blog, but it would be great if over time more from the developer community would be added. I will contribute native provider plugins for Mastodon and Flickr in the next few weeks to reduce the current dependence on brid.gy, where it is no longer necessary.

Provider-Plugin Webmentions (mentions-united-provider_webmentions.js)
Get all interactions from the webmention.io API via the URL of the blog post (target), be they real webmentions or interactions from the platforms Mastodon, Bluesky, GitHub, Flickr and others that have been integrated via brid.gy
Provider-Plugin Pixelfed (mentions-united-provider_pixelfed.js)
Get all interactions from the API of a Pixelfed instance via the syndication URL (source). In the passed options, you can also specify an API proxy URL to prevent the key necessary for the retrieval from being publicly available.
Provider-Plugin DEV.to (mentions-united-provider_devto.js)
Get all comments from the DEV API via the syndication URL

Once all the interactions have been collected, the renderer plugins can integrate them into the page in different ways. It is important to note that the solution outputs pure HTML without any styles, because these are very individual after all.

Renderer-Plugin List (mentions-united-renderer_list.js)
Generates a descending sorted list of all interactions
Renderer-Plugin Avatars by Type (mentions-united-renderer_avatars-by-type.js)
Generates an inline list of avatars for all interactions of a given type, for example Likes
Renderer-Plugin Total Number (mentions-united-renderer_total-number.js)
Creates an anchor with the number of interactions

Additional information about the plugins, the options and many more details can be found on the GitHub repository for the project.

On the original post on kiko.io I give an insight how my implementation looks like under the SSG Hexo ... https://kiko.io/post/Mentions-United-3-2-1-go/

Exploit the feedback potential with syndication links

Kristof Zerbe — Thu, 15 Aug 2024 11:39:24 +0000

With the introduction of my blogroll, my morning routine has changed without me having planned it. By displaying the latest blogger posts there by fetsching them while the site is build once a day, I start reading there instead of in my standard feed reader feedly. I no longer subscribe to the 40 blogs currently on my list, but use Read You as a blogroll reader in case I miss something.

But there's one thing that drives me crazy when I read the posts of my favourite bloggers: As good and entertaining as they write, it's sometimes difficult to give them feedback on their articles!

Some have a comment form, others rely on webmentions, including the display of reactions from Mastodon and other platforms, for example, and still others offer no interaction options with their posts at all, but are limited to links to their social media channels or newsletter subscription forms.

I am absolutely not a fan of comment forms anymore, since the Fediverse and the IndieWeb have taken off in recent years and allow every website operator to provide feedback channels ... Keyword Webmentions, Mastodon-Replies, etc. Who knows where form data such as name, email address and website, which is often mandatory, ends up? It doesn't matter whether the operator has built the comment form themselves or uses Disqus or similar. Having to provide such information is simply no longer necessary today and I therefore avoid it.

I have now analysed the 40 blogs in my blogroll with regard to the interaction possibilities with the posts, whereby multiple answers are possible:

No	Interaction possibility under the article	Count
1	Comment Form	10
2	Contact Me Link	1
3	Like Button	1
4	Webmention Form	2
5	Display Webmentions / Reactions	9
6	Social Media Sharing	3
7	Follow Me Links	19
8	Syndication Links	2
9	Nothing	9

On the other hand, many of these bloggers have syndicated their posts (at least most of the time) on Mastodon, to draw attention to their article:

90% of bloggers therefore theoretically offer the opportunity to react to the article via the syndicated post on Mastodon and just around 22% even provide corresponding reactions such as likes or replies (mostly as webmentions) under the post [4]. But only 5% link from their article to the syndicated post [8] ... and I don't understand why!

Even if you don't know the POSSE principle (Publish on your Own Site, Syndicate Elsewhere), propagated by the IndieWeb movement, it still makes sense to set a reference to your own work on another platform by linking on the original ... after all, we're talking about the web here and the link is still its most powerful tool. After all, not everyone uses Mastodon as a gateway for browsing and reading, but often it is the website via which articles are accessed initially. Keyword: RSS feeds!

Best-Case scenario

I read about a new post via a provided website feed and I open the page to read it. I find below the text a list of reactions already received and a link to the syndicated Mastodon post that people have reacted to. As a Mastodon user, I click on it, am redirected to the post and also respond with a like or a reply. This reaction is also displayed under the post shortly afterwards.

My current scenario with 85% of my blogroll

I find out about a new post via my blogroll, open the page and read. I open the blogger's profile via the Mastodon link and start scrolling until I find the post in which they have promoted the article and respond with a like or a reply.
If there are a few days in between and the blogger is an avid Mastodon user, it can take a while ... and often I just give up and don't give any feedback. Wasted potential.

Raising potential

The ones who make it easiest for me personally and fulfil the best-case scenario are Robb Knight and Jeremy Keith, at least with his notes. Somewhat out of the ordinary is Ryan Barrett whose website does not need syndication links because it is itself part of the Fediverse. Matthias Pfefferle at least shows a link called Reply on the Fediverse in his list of existing reactions, which leads to the reaction, which unfortunately does not lead any further with contributions without reactions.

I myself place the links to the syndications under every article, every note and every photo, even if this means a bit more work after publication because I have to write the links manually in the frontmatter of the post. But for my readers, a reaction is usually just a click away, because I see a post on my website as the starting point for communication. I don't just write for myself, but also for you and it's nice to see when a post elicits a positive reaction or even criticism and perhaps a conversation develops from it, which helps me to make progress. That's why I consider the reactions as part of the post and, like some of my favourite bloggers, display them below the text. Tools for this are bridgy and webmention.io, at least for the Mastodon syndications. Other platforms do not yet offer Webmention support or even an interface to retrieve the reactions, but in the future I would like to connect at least those that do.

Conclusion

I would absolutely welcome it if all website operators started to think in circles and it became irrelevant from which direction I came across a blogger's written thoughts. Everything is linked and referenced to each other and thus enables barrier-free communication.

See the original post on kiko.io: Exploit the feedback potential with syndication links

Push Over Webmentions

Kristof Zerbe — Fri, 02 Aug 2024 07:02:38 +0000

Get notified on your smartphone about an incoming webmention for your site

If you offer Webmentions on your website, i.e. the option of being notified via a link on another website, it is advisable to keep an eye on the incoming mentions. Otherwise, it is all too easy for a page to become a spam sling if you automatically display the incoming messages under an article, as I do using JavaScript.

Such a moderation is not quite simple with static pages, because you cannot receive the mentions yourself, due to the lack of a reactive component on the web server, but need a service such as webmention.io to do this. There, on the dashboard, you can view the list of mentions, delete unwelcome ones and also block entire domains for the future.

The only problem is: How do you get notified promptly that a mention has been received? Checking the dashboard every few days or going through your own posts regularly is not really an option. But we all carry our smartphone with us all the time and it constantly notifies us of new emails, signal messages and the like. Perfect ...

The Trigger

When developing webmention.io, Aaron Parecki kindly thought of implementing a Webhook that posts every incoming mention as JSON to a configurable URL for the site. Here is his example JSON, grabbed from https://webmention.io/settings/webhooks:

{
  "secret": "1234abcd",
  "source": "http://rhiaro.co.uk/2015/11/1446953889",
  "target": "http://aaronparecki.com/notes/2015/11/07/4/indiewebcamp",
  "post": {
    "type": "entry",
    "author": {
      "name": "Amy Guy",
      "photo": "http://webmention.io/avatar/rhiaro.co.uk/829d3f6e7083d7ee8bd7b20363da84d88ce5b4ce094f78fd1b27d8d3dc42560e.png",
      "url": "http://rhiaro.co.uk/about#me"
    },
    "url": "http://rhiaro.co.uk/2015/11/1446953889",
    "published": "2015-11-08T03:38:09+00:00",
    "name": "repost of http://aaronparecki.com/notes/2015/11/07/4/indiewebcamp",
    "repost-of": "http://aaronparecki.com/notes/2015/11/07/4/indiewebcamp",
    "wm-property": "repost-of"
  }
}

For this webhook, all you need is a permanently available recipient who transforms the JSON of the mention into a message for the smartphone.

The Receiver

Classic webhook targets are tools such as IFTTT or Zapier, in which the received data can be converted into any other action as a trigger. However, I have been using a different solution for many years, partly because the former have become too complex and expensive for me ... Pushover.

However, this app for Android and iOS is designed solely for sending push notifications to smartphones. You can connect the above-mentioned services (the list of integrations is quite long), use the built-in mail service or create something yourself using the API, which in the case of the webmention.io hook is both necessary and fairly simple.

Pushover requires registration and a fee for the app, but this is only a one-time charge of $5 USD per device class (e.g. Android) and is well invested. The standard plan allows you to send 10,000 messages per month, which should be sufficient in most cases.

After registering, you can create applications in the dashboard for which you can obtain the necessary API key and which are independent of the devices on which you want to receive the push messages afterwards.

The Transformer

The aim of the custom development is to build a small Web Service that listens for a webhook (POST request) on a dedicated URL, transforms the incoming data into a Pushover message and sends it to the Pushover API in order to trigger a notification on the smartphone.

The choice of the environment was easy: Node JS. I'm a JavaScript aficionado. The basic framework of the web service is pretty straightforward and can be found in many beginner's tutorial:

app.js:

const express = require('express');

const app = express();
const PORT = process.env.PORT || 3000;

app.use(express.json()); //transform payload into JSON

app.post('/webhook', (req, res) => {

  //do something with data in req.body

  res.status(200).send('OK'); //confirm receipt
});

app.listen(PORT, () => {
  console.log(`Webhook receiver listening on port ${PORT}`);
});

The webhook endpoint listens for incoming POST requests, processes the JSON data and sends a confirmation back to the sender. I will skip the complete implementation here, as I have made it available as a project on GitHub:

GitHub: https://github.com/kristofzerbe/webmention-pushover

In the following I describe how you can easily get the service up and running from GitHub, so it is recommended to fork the project, because you will need to make a few adjustments to make it work for your website.

Adjustments

All user-defined parameters are stored in an environment file called .env. This includes the webhook secret, an arbitrary character string that must be entered in webmention.io and is cross-checked in the code, and the Pushover User Key and the Pushover API Key (Token), so that the service knows who is currently sending a message for which registered application and that you get from Pushover:

.env:

PORT=1234
WEBHOOK_SECRET=xxx
PUSHOVER_USER=yyy
PUSHOVER_TOKEN=zzz

xxx, yyy and zzz must of course be replaced by your values. You can also specify a different port here under which the service can later be reached internally on the server, but this does not really matter in live operating mode.

Test

The service is started via the command node app or node app.js.

As it is an API web service that speaks JSON, basically any REST-capable client such as Postman is suitable for testing. I use the plugin REST Client from Huachao Mao in my favourite IDE Visual Studio Code. I just need a suitable .http file and can start the test against the running server within the project with a hotkey. Here is the one I use to test the webhook of a deleted mention and whose payload again comes from Aaron's example:

test/deleted.http:

POST http://localhost:1234/webhook
content-type: application/json

{
  "secret": "8eXANPkiUw4OpVqZRMkSeOn4hipPa7",
  "source": "http://rhiaro.co.uk/2015/11/1446953889",
  "target": "http://aaronparecki.com/notes/2015/11/07/4/indiewebcamp",
  "deleted": true
}

Here is the output in the command line... :

... and the result on the smartphone via Pushover app:

The Hosting

The 72 lines of NodeJS code of the webmention-pushover service now need to be installed and hosted in a central location, accessible from anywhere on the Internet. The simplest and cheapest, because it is free, option is Render. Installation and deployment is foolproof, to say the least, because you simply link your GitHub project, configure the service and Render does the rest, such as automatically deploying new versions. Commit and forget ...

Yogesh Chavan has written a really helpful guide on freecodecamp.org: How to Deploy Your Node.js Application for Free with Render

In our case, only two values need to be adjusted in the settings:

Setting	Value
Build Command	npm install
Start Command	node app

When the web service is installed, it is automatically assigned a URL by Render. In my case, this is https://webmention-pushover.onrender.com. If you like, you can also redirect this to your own domain via Custom Domains in the settings.

The logs in the dashboard are quite helpful to see what the service is doing:

Free services are spinned off by Render after a certain period of inactivity and with the next incoming request it takes a few seconds until it is back, but this is no problem for webmention.io.

The Linking

The last step is now to link the running webhook transformation service to webmention.io.

All you have to do is to enter the new service URL, including the endpoint /webhook, and the previously created WEBHOOK_SECRET into the Web Hook settings of webmention.io:

Conclusion

The process is very simple in general ...

All you have to do afterwards is remove the one or other webmention that you are notified about and do not want on your site via the webmention.io dashboard and, if necessary, block an entire domain.

If you have any questions, please do not hesitate to ask me. Happy mentioning ;)

Ensure Accessibility on Icon Links

Kristof Zerbe — Thu, 25 Jul 2024 16:58:43 +0000

... automatically with a small client-side script

I am gradually saying goodbye to icon fonts in this blog in favor of SVG files, which I prefer to integrate using background-image in order to remain flexible.

During the modification, I noticed that although I have sometimes provided icon-only links with a title, these do not play any role in terms of accessibility. People who are dependent on a screen reader have not yet been able to recognize what these links are.

Where were two ways to change this: aria-label or add text and make it invisible. The former is basically just a crutch that is not even fully supported by all browsers and so only the invisible text remained. I found a suitable and very well-working solution on Stack Overflow by GrahamTheDev:

<a class="my-icon-link" title="My Link">
  <span class="visually-hidden">My Link</span>
</a>

.my-icon-link {
  background-image: url(/images/icons/my-icon.svg);
}

.visually-hidden { 
  border: 0;
  padding: 0;
  margin: 0;
  position: absolute !important;
  height: 1px; 
  width: 1px;
  overflow: hidden;
  clip: rect(1px 1px 1px 1px); /* IE6, IE7 - a 0 height clip, off to the bottom right of the visible 1px box */
  clip: rect(1px, 1px, 1px, 1px); /*maybe deprecated but we need to support legacy browsers */
  clip-path: inset(50%); /*modern browsers, clip-path works inwards from each corner*/
  white-space: nowrap; /* added line to stop words getting smushed together (as they go onto seperate lines and some screen readers do not understand line feeds as a space */
}

My task was now to extend all textless icon links in the code with the SPAN ... or to find an automatism for this, because all these links already have a title and it is exactly what needs to be transferred to the link text. Since accessibility is not impaired when text is injected via JavaScript, I have found the following client-side solution, which is embedded in the footer of each page via script:

function ensureIconLinkText() {
  let linksWithoutText = document.querySelectorAll("a[href^='http']:empty");
  linksWithoutText.forEach(e => {
    if (window.getComputedStyle(e).display !== "none") {
      if (e.title) {
        let eText = document.createElement("span");
        eText.innerText = e.title;
        eText.classList.add("visually-hidden");
        e.append(eText);
      } else {
        console.error("Link without Text and Title: " + e.outerHTML);
      }
    }
  });
}

ensureIconLinkText();

The code in text form:
Find all A tags without text, run through them and if the element was not intentionally hidden and if a title is defined, create a new SPAN tag with its text value und insert this into the link, otherwise output an error in the console

With this approach, I can leave the links as they are and can see in the console whether I have forgotten a title somewhere.

My-well-known-feeds-and-thoughts-beyond

Kristof Zerbe — Wed, 24 Jul 2024 09:20:29 +0000

Every idea has to start somewhere

Triggered by Dan Q.'s post '.well-known/feeds', in which he suggests using a consistent per-site file along the lines of the resource identifier pattern .well-known for providing feeds, instead of placing links on all individual pages, I have summarised my feeds accordingly today, simply because this solution feels more correct to me.

His approach is actually quite smart, because he simply combines two existing techniques: OPML (Outline Processor Markup Language) and those well-known URI's. It was therefore not particularly difficult for me to create such a file. I do exactly the same with my blogroll, only now the feeds are my own, in different formats and variants.

Every idea has to start somewhere

... as Colin Walker said in his comment.

Here's my .well-known/feeds:

<?xml version="1.0" encoding="UTF-8"?>
<opml version="2.0">
  <head>
    <title>kiko.io&#x27;s Feeds</title>
    <dateCreated>2023-08-30T12:47:33.000Z</dateCreated>
    <ownerName>Kristof Zerbe</ownerName>
    <ownerEmail>kristof.zerbe@gmail.com</ownerEmail>
    <ownerId>https://kiko.io</ownerId>
    <docs>https://kiko.io/feeds</docs>
  </head>
  <body>
    <outline text="Atom Feed (Full Content)" type="rss" version="ATOM1" xmlUrl="https://kiko.io/atom.xml" htmlUrl="https://kiko.io" description="Last 20 posts as Atom feed"/>
    <outline text="Atom Feed (Excerpt)" type="rss" version="ATOM1" xmlUrl="https://kiko.io/atom-excerpt.xml" htmlUrl="https://kiko.io" description="Last 20 posts with excerpt only as Atom feed"/>
    <outline text="RSS Feed (Full Content)" type="rss" version="RSS2" xmlUrl="https://kiko.io/rss.xml" htmlUrl="https://kiko.io" description="Last 20 posts as RSS feed"/>
    <outline text="RSS Feed (Excerpt)" type="rss" version="RSS2" xmlUrl="https://kiko.io/rss-excerpt.xml" htmlUrl="https://kiko.io" description="Last 20 posts with excerpt only as RSS feed"/>
    <outline text="JSON Feed (Full Content)" type="rss" version="JSON1" xmlUrl="https://kiko.io/feed.json" htmlUrl="https://kiko.io" description="Last 20 posts as JSON feed"/>
    <outline text="JSON Feed (Excerpt)" type="rss" version="JSON1" xmlUrl="https://kiko.io/feed-excerpt.json" htmlUrl="https://kiko.io" description="Last 20 posts with excerpt only as JSON feed"/>
    <outline text="HTML Microformats Feed (Excerpt)" type="rss" version="MF2HTML" xmlUrl="https://kiko.io/feeds/index.html" htmlUrl="https://kiko.io" description="Last 20 arcticles with excerpt only as HTML Microformats feed"/>
  </body>
</opml>

The OPML 'type' problem

Dan lists his different feeds (among other links) in his file, which differ in content, but are always in the same RSS format. In contrast, I actually only have two different content types, full and excerpt, but in 4 different formats: RSS, Atom, JSON and MF2/HTML. Depending on taste.

There is a problem that Ruben Schade already noticed in 2021: OPML requires the value rss as type, i.e. other types such as atom or the like are not provided. Dave Winer writes quite succinctly in the spec:

Each sub-element of the body of the OPML document is a node of type rss or an outline element that contains nodes of type rss.

The only space that opens up here is the use of the version attribute, but that is just speculation. Although Dave uses it by himself in one of his OPML examples (RSS1), the spec says:

There are no known values for Atom feeds, but they certainly could be provided.

Hmmm, take it or leave it? But how else am I supposed to distinguish between the 4 different formats in the OPML? Like Ruben, I have decided to simply put the values that make the most sense to me in version:

ATOM1
RSS2
JSON
MF2HTML

Let's see what happens ... especially as Dan's OPML approach is still a proposal. The one is only partly related to the other, but if .well-kown/feeds becomes more popular, maybe there will be an update to OPML where you can use the type what it seemed to be intended for.

Thoughts beyond ...

In my post yesterday, I reported on the refactoring of my blog's HEAD, which of course also mentioned the ALTERNATE links for the feeds, which the new file could replace.

If you now take a closer look at the META information, not only does the latter apply to the entire site, but also:

meta name="generator"
link rel="me"
link rel="webmention | pingback"
link rel="blogroll"
link rel="search"
link rel="manifest"
meta name="theme-color"
meta name="color-scheme"

... and of course a large part of the JSON-LD that does not refer to the individual page, such as the @type's WebSite, Organisation and Person.

All of this information also applies on a site-per-site basis and why not make it available to the user agent centrally and save some bytes when delivering the pages as a nice additional effect? (Not that web developers sometimes leave no stone unturned in order to save characters and thus bandwidth, but are forced to use dozens of lines in the header).

Of course there is some META information that can differ from page to page, such as meta name="author", but with personal blogs there is only ever one person who can be considered as the author. This could therefore also be moved to a kind of .well-known/site-meta. (Not to be confused with the existing host-meta).

Interestingly, Dan takes up the topic indirectly, because in his OPML there are two blocks: Blog (with the feeds) and Elsewhere, in which only the first URL is actually of the rss type and the others are simply profile links to GitHub, YouTube and others. At least link rel="me" has already been mapped this way, which I would not have expected from a feed resource.

From my point of view, something like this could make sense, but is not yet fully thought out:

<?xml version="1.0" encoding="UTF-8"?>
<opml version="2.0">
<head>
    <title>kiko.io&#x27;s Site Meta</title>
    <dateCreated>2023-08-30T12:47:33.000Z</dateCreated>
    <ownerName>Kristof Zerbe</ownerName>
    <ownerEmail>kristof.zerbe@gmail.com</ownerEmail>
    <ownerId>https://kiko.io</ownerId>
  </head>
  <body>
    <outline text="Site" purpose="site">
      <outline text="Name" purpose="name" content="kiko.io"/>
      <outline text="Url" purpose="url" content="https://kiko.io"/>
      <outline text="Author" purpose="author" content="Kristof Zerbe"/>
      <outline text="Fediverse Creator" purpose="fediverse:creator" content="@kiko@indieweb.social"/>
      <outline text="Locale" purpose="locale" content="en_US"/>
      <outline text="Type" purpose="type" content="Blog"/>
      <outline text="Generators" purpose="generator">
        <outline text="Hexo 7.2.0" type="link" url="https://hexo.io"/>
      </outline>
      <outline text="Licenses" purpose="license">
        <outline text="CC BY-SA 4.0" type="link" url="https://creativecommons.org/licenses/by-sa/4.0/"/>
        <outline text="CC BY-SA 4.0 (RDF)" type="xml" version="RDF" xmlUrl="https://creativecommons.org/licenses/by-sa/4.0/rdf"/>
      </outline>
      <outline text="Profiles" purpose="me">
        <outline text="Mastodon" type="link" url="https://indieweb.social/@kiko"/>
        <outline text="GitHub" type="link" url="https://github.com/kristofzerbe" auth="true"/>
        <outline text="Mail" type="link" url="mailto:kristof.zerbe@gmail.com" auth="true"/>
      </outline>
      <outline text="Webmention" purpose="webmention" type="link" url="https://webmention.io/kiko.io/webmention"/>
      <outline text="Pingback" purpose="pingback" type="link" url="https://webmention.io/kiko.io/xmlrpc"/>
      <outline text="Blogroll" purpose="blogroll" type="xml" version="opml" xmlUrl="https://kiko.io/blogroll.xml"/>
      <outline text="Search" purpose="search" type="xml" version="opensearchdescription" xmlUrl="https://kiko.io/opensearch.xml"/>
      <outline text="Icon" purpose="icon" type="link" url="https://kiko.io/favicon.ico">
      <outline text="Web Manifest" purpose="manifest" type="json" jsonUrl="https://kiko.io/manifest.json"/>
      <outline text="Theme Color" purpose="theme-color" content="#444"/>
      <outline text="Color Scheme" purpose="color-scheme" content="light dark"/>
      <outline text="Feeds" purpose="feeds">
        <outline text="Atom Feed (Full Content)" type="atom" version="ATOM1" xmlUrl="https://kiko.io/atom.xml" htmlUrl="https://kiko.io" description="Last 20 posts as Atom feed"/>
        <outline text="Atom Feed (Excerpt)" type="atom" version="ATOM1" xmlUrl="https://kiko.io/atom-excerpt.xml" htmlUrl="https://kiko.io" description="Last 20 posts with excerpt only as Atom feed"/>
        <outline text="RSS Feed (Full Content)" type="rss" version="RSS2" xmlUrl="https://kiko.io/rss.xml" htmlUrl="https://kiko.io" description="Last 20 posts as RSS feed"/>
        <outline text="RSS Feed (Excerpt)" type="rss" version="RSS2" xmlUrl="https://kiko.io/rss-excerpt.xml" htmlUrl="https://kiko.io" description="Last 20 posts with excerpt only as RSS feed"/>
        <outline text="JSON Feed (Full Content)" type="json" version="JSON1" xmlUrl="https://kiko.io/feed.json" htmlUrl="https://kiko.io" description="Last 20 posts as JSON feed"/>
        <outline text="JSON Feed (Excerpt)" type="json" version="JSON1" xmlUrl="https://kiko.io/feed-excerpt.json" htmlUrl="https://kiko.io" description="Last 20 posts with excerpt only as JSON feed"/>
        <outline text="HTML Microformats Feed (Excerpt)" type="mf2html" version="MF2HTML" xmlUrl="https://kiko.io/feeds/index.html" htmlUrl="https://kiko.io" description="Last 20 arcticles with excerpt only as HTML Microformats feed"/>
      </outline>
    </outline>
  </body>
</opml>

I could well imagine taking some of the weight off my pages, because this information should actually be centralised.

Your thoughts?

Head Care - Cleaning up META and LINK tags

Kristof Zerbe — Thu, 18 Jul 2024 19:07:47 +0000

Actually, I just wanted to add the blogroll link tag to the header of my blog, which Dave Winer mentioned in a comment on Dan Q's post .well-known/feeds. But since I was already in my head.ejs, I tidied up and reorganised it a bit. It's like a basement: you just put things in there and at some point it looks messy.

So I went through every META and LINK tag and researched it in documentaries or pseudo-documentaries and also looked at a lot of page sources from sites whose creators should know how to do it. The picture wasn't consistent, how could it be otherwise, but I did pick up a few things, including new ones, and integrated them in my head. (Nice wordplay)

meta name="viewport"

This HTML5 classic has remained unchanged and is essential for a responsive web design. It tells the browser how to control the dimensions and scaling of the viewport.

<meta name="viewport" content="width=device-width, initial-scale=1">

More Info:

MDN Web Docs: Viewport meta tag

meta name="generator"

This tag indicates which software was used to generate a website and I have noticed it in some page source texts and it is also included in the HTML5 specs. I couldn't find out what deeper meaning this information has for browsers/crawlers et al, but I'm always up for useless but descriptive things :)

<meta name="generator" content="Hexo 7.2.0">

More Info:

whatwg.org: HTML Standard - Standard metadata names

link rel="canonical"

One of the most important link tags intended for search engines, it indicates whether a page is "canonical", i.e. the only true source of information. It identifies the preferred and most representative version of a piece of content that may be available on several URLs and prevents it from slipping down the search engine index due to duplicates.

<link rel="canonical" href="https://kiko.io/post/Head-Care/">

More Info:

Wikipedia: Canonical link element
Google Search Central: How to specify a canonical with rel="canonical" and other methods

meta name="title | description | excerpt"

These three tags form the foundation for all automatic processing of a page, be it search engines, social media services or those from the federated web. Without them, there are no headlines or teaser texts on Google and Co. and you will probably not even be included in the index.

I keep fiddling around with the excerpt again and again, because it is sometimes quite complex to generate a reasonable text excerpt from my Markdown content. I haven't found the ultimate solution yet. At the moment I'm trying to help myself with RegEx and a few libs.

By the way, I have completely stopped offering meta keywords at this point. They don't really work anyway and are more of a relic from the past.

<meta name="title" content="Head Care - kiko.io">
<meta name="description" content="Cleaning up META and LINK tags">
<meta name="excerpt" content="Actually, I just wanted to add ... [more text]"

More Info:

whatwg.org: HTML Standard - Standard metadata names

meta property="og: ..."

Open Graph, and thus the og: meta tags, is an invention of Facebook, but is now very widespread, open source and has become a near-standard. It defines attributes that make an object, in this case a web page, an object in a social graph. We already know url, title and description from other meta tags, which are repeated here but enriched with additional attributes. I find og:image as a very useful way of specifying a representation image that is displayed as a visual equivalent when linking to a Facebook or Mastodon post, for example.

<meta property="og:site_name" content="kiko.io">
<meta property="og:type" content="blog">
<meta property="og:url" content="https://kiko.io/post/Head-Care/">
<meta property="og:title" content="Head Care - kiko.io">
<meta property="og:description" content="Cleaning up META and LINK tags">
<meta property="og:logo" content="https://kiko.io/images/icon-192x192.png" />
<meta property="og:image" content="https://kiko.io/images/social-media/Head-Care.png">
<meta property="og:locale" content="en_US">

More Info:

The Open Graph protocol

meta property="twitter: ..."

The so-called Twitter Card Tags were a kind of counter-design from Twitter to Facebook's Open Graph and generally complement it today. I don't really fancy anything that comes out of Elon Musk's social media toy shop any more, but for the sake of tradition and to remain compatible, I'm leaving them in as they are.

What do you think? Should they be taken out?

<meta property="twitter:card" content="summary_large_image">
<meta property="twitter:url" content="https://kiko.io/post/Head-Care/">
<meta property="twitter:title" content="Head Care - kiko.io">
<meta property="twitter:description" content="Cleaning up META and LINK tags">
<meta property="twitter:image" content="https://kiko.io/images/social-media/Head-Care.png">

More Info:

Twitter Developer Platform: Getting started with Cards

link rel="license"

I have copied these two tags from Matthias Pfefferle's notizBlog. I think it's good to make it machine-readable under which conditions the output of my brain and fingers can be used by others. Until now, I only had a corresponding badge with a link on my photos page.

<link rel="license" href="https://creativecommons.org/licenses/by-sa/4.0/" type="text/html" />
<link rel="license" href="https://creativecommons.org/licenses/by-sa/4.0/rdf" type="application/rdf+xml" />

More Info:

CreativeCommons: CC REL by Example
Microformats Wiki: rel="license"

meta name="author"

So that everyone knows who is responsible by name for what you are forced to read here, there is this tag. However, there is always discussion as to whether this should be the web creator or the author of the text. In my case, it doesn't make any difference.

<meta name="author" content="Kristof Zerbe">

More Info:

whatwg.org: HTML Standard - Standard metadata names

meta name="fediverse:creator"

Here's the newest kid in town ... launched by the creators of Mastodon to make journalists and others in the writing world more visible. It allows authors who work with multiple publishers or platforms to link directly to their presence in the Fediverse and thereby connecting the users to the person itself. Syndicated posts from platforms that support the new feature will have a link to the author's handle below the post. I don't really need that thing, but it's neat and who knows what else the Fedi people will come up with.

<meta name="fediverse:creator" content="@kiko@indieweb.social">

More Info:

Mastodon Blog - Eugen Rochko: Highlighting journalism on Mastodon
Chris McLeod: Adding the New Mastodon Link Attribution Meta Tag

link rel="me"

I use these tags to link my blog to my other identities/profile pages on the web to show that the same person is represented on both sides. A simple identity verification, which is also the foundation for IndieWeb authentication services such as IndieAuth, as used on webmention.io, for example. With the additional authn I select which providers are considered for authentication. Mastodon uses this for the green tick in the profile also.

<link rel="me" href="https://indieweb.social/@kiko">
<link rel="me authn" href="https://github.com/kristofzerbe">
<link rel="me authn" href="mailto:kristof.zerbe@gmail.com">

More Info:

IndieWeb: rel-me
Microformats Wiki: RelMeAuth
auth.hawx.me: relme-auth - Sign in with your domain

link rel="webmention | pingback"

This blog is a static one and lives on GitHub Pages, i.e. there is no reactive component in the background that could respond to any kind of request, apart from retrieving pages. However, if someone wants to send me a so-called Webmention (or a slightly older Pingback), someone should answer and in my case this is the fabulous Webmention.io service from Aaron Parecki and I let all requesters know this, with these two tags.

<link rel="webmention" href="https://webmention.io/kiko.io/webmention" />
<link rel="pingback" href="https://webmention.io/kiko.io/xmlrpc" />

More Info:

IndieWeb: Webmention
Jan Monschke: Adding webmentions to your static blog
(myself): Hexo and the IndieWeb (Receiving Webmentions)

link rel="blogroll"

Now let's get to the main reason for this post ... (see introduction above). I've had a lot of fun implementing my own blogroll into my SSG Hexo over the last few weeks and the news that someone is trying to bring the many blogrolls on the web together is exciting. No one knows exactly what that might look like yet, but it's like Dan Q. says:

Now all we need is some tools that can do such detection!

<link rel="blogroll" type="text/xml" href="https://kiko.io/blogroll.xml" title="kiko.io&#39;s Blogroll">

More Info:

Dan Q.: link rel="blogroll"
opml.org (Dave Winer): About blogrolls

link rel="search"

Last year I integrated a search via Pagefind into this blog and thus made myself a little less dependent on Google. What I forgot to do is to technically explain to a search engine how my search mechanism can be used so that the user can go directly from the search to my search results. This can be done via an XML file in OpenSearch description format

<link rel="search" type="application/opensearchdescription+xml" href="https://kiko.io/opensearch.xml" title="kiko.io"/>

More Info:

Arthur Denner: How to implement a search shortcut (OpenSearch) on any website
Microsoft Learn: Creating an OpenSearch Description File in Windows Federated Search
MDN Web Docs: OpenSearch description format

script type="application/ld+json"

Of course, my head element also contains the JSON-LD script that I wrote about over a year ago and which I suspect will basically replace the meta and link tag world in the long run with regard to search engines, because it's simply better structured and can probably be processed more easily as the stuff above.

<script type="application/ld+json">{ "@context":"http://schema.org/", ... [more code] }</script>

More Info:

Google Search Central: Introduction to structured data markup in Google Search
(myself): Provide Blog Metadata via JSON-LD

link rel="alternate"

It's always good to make things easy for your users. This also applies to finding a feed on a website, in whatever form. For the so-called feed autodiscovery specified in HTML5, alternate link tags with the corresponding MIME type are used. I have integrated several different feeds (Atom, RSS, JSON and HTML) on my site and placed the variants with the complete text in the autodiscovery.

What appeals to me now is what Dan Q. brought up in the post in the introduction to this article: .well-known/feeds. Let's see if I can tinker with it tonight or tomorrow ...

<link rel="alternate" type="application/atom+xml" href="https://kiko.io/atom.xml" title="kiko.io&#39;s Atom Feed (Full Content)">
<link rel="alternate" type="application/rss+xml" href="https://kiko.io/rss.xml" title="kiko.io&#39;s RSS Feed (Full Content)">
<link rel="alternate" type="application/json" href="https://kiko.io/feed.json" title="kiko.io&#39;s JSON Feed (Full Content)">
<link rel="alternate" type="application/mf2+html" href="https://kiko.io/feeds/index.html" title="kiko.io&#39;s HTML Microformats Feed (Excerpt)">

More Info:

The WHATWG Blog: Feed Autodiscovery
whatwg.org: HTML Standard - Link type "alternate"
Microformats Wiki: rel-alternate
Jim Nielsen: Making Your RSS Feeds Automatically Discoverable

link rel="manifest"

Is a blog an app? I think so. An app for reading stuff. That's why it makes sense for me to technically raise my blog to the same level as WebApps/PWA's by offering a corresponding manifest, that shows the browser how to install kiko.io on the system, if the user want to.

<link rel="manifest" href="/manifest.json">

More Info:

MDN Web Docs: Web app manifests

link rel="icon | apple-touch-icon"

In addition to the information on the manifest, which already contains pretty much all the information a browser needs to display the website nicely on his OS, this classic is part of the standard repertoire and should not be missing. Nothing is duller than a browser tab without an icon. Since Apple always does everything a little differently, a PNG image should be provided for iOS.

As with all resources, relative paths are useful here so that the site is also displayed correctly during local development.

<link rel="icon" href="/favicon.ico">
<link rel="apple-touch-icon" href="/images/apple-touch-icon.png">

More Info:

W3C: How to Add a Favicon to your Site
webhint: Use Apple Touch Icon

meta name="theme-color"

This tag is similar to the icon and can also be found in the manifest, but it is not a bad idea to tell the browser the desired color for the environment in this way too.

<meta name="theme-color" content="#444">

More Info:

MDN Web Docs: theme-color

meta name="color-scheme"

The color-scheme tag points in a slightly different direction than the previous one. It can be used to specify whether and which color scheme the website supports: light or dark or both. I am a great advocate of individual theme switches, but for this you first have to implement and offer two different themes in the CSS. This tag makes the presence of these known to the browser.

I have also used the tag so far and built a theme switch around it, but I have overlooked one thing:

Providing both keywords indicates that the first scheme is preferred (by the author), but the second is also acceptable if the user prefers it instead.

I've defined them the wrong way round so far, as I'm not a fan of dark themes and prefer the light ones.

<meta name="color-scheme" content="light dark">

More Info:

web.dev (Thomas Steiner): Improved dark mode default styling with the color-scheme CSS property and the corresponding meta tag

link rel="preload"

I use special web fonts and an individual photo for each page. To preload these files before they are actually used, it makes sense to use the PRELOAD link, which tells the browser: "Hey, I'm going to need this anyway. Load it now".

It is essential to inform the browser of the correct MIME type of the resource and to indicate the specific class via the as attribute. The additional attribute crossorigin is only required if the resource is not located on your own server, as it is then retrieved using a CORS request.

<link rel="preload" as="font" type="font/woff2" href="/css/fonts/lexend/webfonts/Lexend-ExtraLight.woff2">
...
<link rel="preload" as="image" type="image/jpeg" href="/images/social-media/Head-Care.png" imagesrcset="/images/social-media/Head-Care.png 480w, /images/social-media/Head-Care.png 768w">

More Info:

MDN Web Doc: rel=preload
whatwg.org: HTML Standard - Link type "preload"

link rel="stylesheet"

Yes, of course. For the sake of completeness, I have to mention the links via which the CSS is loaded into the page as an external resource also. Without these, the web would look dull and empty.

<link rel="stylesheet" href="/css/dist/asset-bundle.min.css">
<link rel="stylesheet" href="/css/style.css">

More Info:

MDN Web Docs: The External Resource Link element
freeCodeCamp: How to Link CSS to HTML – Stylesheet File Linking

Conclusion

Small cause, big effect. I learnt a lot from refactoring my HEAD and I have to admit that I'm tempted to take a closer look at all those extensions. I would at least be satified, if the work I have done here, can also improve your header a little.

Happy Coding :)

Batman Comics with pure CSS

Kristof Zerbe — Thu, 11 Jul 2024 09:46:39 +0000

I really can't say that I'm a big fan of TailwindCSS, because I don't like decorating my HTML with dozens of predefined classes instead of implementing a meaningful class directly in my own CSS code.

However, Alvaro Montoro shows how you can use predefined classes in a meaningful and even hilarious way with his Batman-Comic.CSS project, which enables you to create a comic without having the slightest idea about drawing comics!

Define the basic structure, add CSS classes for the various facial expressions, add texts for the speech bubbles ... Done. It's so amazingly cool and I think I will use it frequently in my posts, because sometimes a comic says more than a thousand words.

Here is a classic ... consisting of 10 HTML tags and a linked CSS file (and some tiny style adjustments ;):

(Just a picture here on dev.to)

See the original post on kiko.io: Batman Comics with pure CSS

IndieFediWebVerse

Kristof Zerbe — Wed, 27 Dec 2023 14:53:21 +0000

Today I was listening to Mike McCue's Dot Social podcast where he talks with Eugen Rochko about Mastodon and ActivityPub. At around 12:30 Eugen talked about Twitter and the fact that Tumblr is willing to join the Fediverse network and he asked a question, which he immediately tried to improve again:

I think that is the future, because why should we have all these different accounts ... ehh ... like ... ehh ... all these different experiences that are required to connect with different people, when we could have just one account and connect with everyone who uses different services just from one account?

Video, The State of the Federation, with Mastodon’s Eugen Rochko

This slip of the tongue and Eugens emphasis on "ONE account" hit me, because it points to something that has bothered me about Fediverse so far, as wonderfully open and forward-looking as it is:

It doesn't free me from the need to be a duplicate of myself everywhere in the form of an account.

... because I'm not only a Mastodon, Pixelfed or <you name it > user. I'm me at kiko.io in the first place!

My home website is my castle

I consider my website kiko.io to be the center of my digital and public persona. This is me, in terms of longer articles about this and that and an initial place for my photos, that are suitable for a wide audience. From here I transport my content to other channels like Mastodon, dev.to or photo platforms like Pixelfed and some old classic silos like Flickr or 500px.

This syndication is done manually and I'm fine with that at the moment. For one thing, some platforms have no API at all and for another, they all have a slightly different post structure or even length limits. Tools like Bridgy Fed, which turn a website into its own Fediverse actor, won't help me and I don't really want that either, because I want to decide on the form of distribution myself. Maybe one day there will be an AI-driven tool that will help me to summarize my content in my own language specifically for the platform I want my content to syndicate and post it with a click. But for now I want to decide how, where and when.

But my point here is a different one: I am the owner, creator and operator of this blog, or to put it in ActivityPub language: @me@kiko.io. But I am not only interested in publishing my articles or photos, but also in communicating in other ways, away from my own content, but still with reference to myself and my main identity.

On Mastodon, however, I am @kiko@indieweb.de and on Pixelfed you interact with @kristofz@pixelfed.social because the name 'kiko' was already taken. To get to the point: I always appear on the platforms as someone else, away from my main identity. I chat with one identity, comment on a photo with another and like a book review with a completely different one. It's a bit of a split personality a la Dr. Jekyll and Mister Hyde, but it should be always @me@kiko.io, or at least something like that.

The difference between the classic web services and all Fediverse services is, that they are interoperable, so you need and get an address and not just a login name and password. But they behave in this particular way like the classic services: they create the address on their domain for you after you have logged in with your username and password. You can't bring the address with you.

The only widely known interoperable service where this is not the case is email, which is often used as an example for comparison with the Fediverse. Of course you can also use a Gmail or Yahoo mail address, but in my case me@kiko.io is a working mail address, even if I rarely use it. This is not possible in the Fediverse.

I recently tried to make my main identity discoverable using a WebFinger file, at least in the Fediverse, but is less than a crutch and has its pitfalls.

I would like to see some sort of alias system where you can choose which alias of your main identity you want to use on each platform. Using the main identity doesn't work if you are active on more than one platform because the Fediverse inbox/outbox system requires a unique address. But @mastodon@kiko.io or @pixelfed@kiko.io would work. Along a pattern such as @{Platform}@{Own Domain} ... or even better and more flexible by a Webfinger-like file on your (static) website which defines the endpoints of a particular alias of your main identity to the plattform.

For example, if I no longer want to run Mastodon via indieweb.social (Tim, that will never happen), then I export my data there, import it to mastodon.social, for example, and just change the endpoint of the address @mastodon@kiko.io in my file, deploy and I'm done. Full control.

Now, if we imagine there was a tool that could collect and aggregate the interactions that occur in the inboxes of such main identity aliases under the full control of the domain owner, would feel like a dream come true, at least for me. I appreciate brid.gy and webmention.io and the work of their authors and operators Ryan Barret and Aaron Parecki, but these tools are band-aids to make the shortcomings of today's Fediverse somewhat bearable.

Unfortunately, I am not in a position or capable to implement everything like this technically, even if I understand the principles behind all the stuff, but surely there is someone out there with similar ideas and the skills to go with it.

This reorganization or rather evolution of the Fediverse would really be a liberation from the old ways of functioning and would actually give control back to the users, who are the real basis of social media platforms.

A little more IndieWeb would be good for the Fediverse. Just in the direction of a IndieFediWebVerse...

See the original post on kiko.io: IndieFediWebVerse

Hexo, WebFinger and better discoverability

Kristof Zerbe — Fri, 08 Dec 2023 15:25:56 +0000

Recently I read the blog post "Mastodon on your own domain without hosting a server" by Maarten Balliauw, which dealt with how to become more visible in the Fediverse, more precisely in Mastodon, with your own domain, because in contrast to the Indieweb approach, the Fediverse relies on Actors (@USER@INSTANCE) of the respective instance/platform and can only include your own domain, if it becomes a Fediverse endpoint itself.

In my case, the latter is not possible because this blog is a static site, generated via Hexo and hosted on GitHub. It simply lacks a modifiable active server component.

However, Maarten has found a trick to at least make it findable in Mastadon via his own domain. First, he explains how Fediverse platforms work in general:

-- Mastodon (and others) use ActivityPub as their protocol to communicate between "actors".
-- Actors are discovered using WebFinger, a way to attach information to an email address, or other online resource.
-- WebFinger lives on /.well-known/webfinger on a server.

His idea was to simply copy the WebFinger file to his server and make it available in the same way, to allow the Fediverse server to find the correct actor, so search for @me@mydomain.xxx and find @me@my-fediverse-instance.xxx.

Copy a file and deliver it via Hexo over .wellknown/webfinger? What can be so difficult about that...

Download the WebFinger file

As Maarten describes, the WebFinger file (JSON) can always be found on a URL according to the following pattern:

https://<your mastodon server>/.well-known/webfinger?resource=acct:<your account>@<your mastodon server>.

I have my Mastodon account 'kiko' at indieweb.social and the path to the download was accordingly: https://indieweb.social/.well-known/webfinger?resource=acct:kiko@indieweb.social.

Solution 1 - Copy and provide as static file

First of all, Hexo knows nothing about static files. You have to teach it, for example, using the hexo-generator-copy plugin, which I did a long time ago because I deliver a lot of such files, like images, photos, manifests and so on.

Including the WebFinger file in the .wellknown folder in the generation was therefore an obvious choice ... but did not work, as the plugin ignores all files and folders that begin with a dot or underscore. This doesn't matter on Windows, but it probably does on other platforms, so I wanted to leave the plugin's code untouched and wrote another generator that then generates the file separately into the output:

const log = require('hexo-log')({ debug: false, silent: false });
const path = require('path');
const fs = require('hexo-fs');

hexo.extend.generator.register("wellknown-webfinger", async function() {

  log.info("Processing .well-known/webfinger ...");

  const _rootPath = hexo.base_dir;
  const _path = ".well-known/webfinger";

  let content = "";

  let filePath = path.join(_rootPath, this.config.static_dir, _path);
  if (fs.existsSync(filePath)) { 
    json = JSON.parse(fs.readFileSync(filePath)); 
    content = JSON.stringify(json); // flatten JSON
  }

  let result = {
    data: content,
    path: _path
  };

  return result;
});

The whole thing is not magic, because it simply reads the local file from /static/.wellknown/webfinger and returns the output path and the flattened content to be rendered as the result.

But somehow it didn't feel right to first download a file manually and then bypass a generator with another generator in order to deliver the file.

Solution 2 - Download and deliver during generation

A short time later, I deleted the local file again and rewrote the generator, because the first solution didn't make sense to me. Generating my blog now takes less than a minute anyway, so it doesn't matter whether I fetch the WebFinger file directly from the server and write it straight to the output via hexo.route.set:

const log = require('hexo-log')({ debug: false, silent: false });
const axios = require("axios");

hexo.extend.generator.register("wellknown-webfinger", async function() {

  log.info("Processing .well-known/webfinger ...");

  const url = 
    `https://${this.config.mastodon.server}/.well-known/webfinger?resource=acct:${this.config.mastodon.user}@${this.config.mastodon.server}`;

  const _path = ".well-known/webfinger";

  axios.get(url).then(response => {
    let json = response.data;
    hexo.route.set(_path, json);
  });

});

The Result

After deploying to GitHub I was able to search on a Fediverse platform for @kristof@kiko.io and the result is the corresponding account of my Mastodon instance. :)

However, this currently only works with one instance and the user specification is arbitrary (as Maarten also notes). For example, if I search on Pixelfed, my Mastodon account is also displayed, but not my Pixelfed account, which is also available there, because I have not integrated Pixelfeds WebFinger file.

As mentioned above, the Fediverse works a little differently than the Indieweb. My wish would be to find something that identifies me with my domain everywhere.

See the original post on kiko.io: Hexo, WebFinger and better discoverability