In my article about choosing my blog stack, I mentioned wanting to connect this blog to the Fediverse. The idea: let people follow me from Mastodon or Bluesky, and get their interactions directly on my articles. No comment system to manage, no spam, no GDPR headaches. Just conversations.

And here we go again: I developed a Grav plugin for this with a lot of help from Claude. It relies on Bridgy Fed and handles all the technical stuff under the hood. Let me explain how it works and the struggles I encountered along the way.

TL;DR

For those in a hurry, here's the journey:

• Create an account on Bridgy Fed by linking your domain
• Install the plugin on your Grav
• When you publish an article, the plugin notifies Bridgy Fed which creates a post on the Fediverse
• When someone interacts (like, boost, reply), Bridgy Fed sends you the info via Webmention
• The plugin stores and displays these interactions on your article

What is Bridgy Fed?

Bridgy Fed is a free service created by Ryan Barrett. Its purpose: bridge your website to the Fediverse (Mastodon, Bluesky, etc.) without having to host an ActivityPub server yourself.

Concretely, Bridgy Fed:

• Creates a Fediverse identity for your domain (like @trucs.hophop.be@trucs.hophop.be)
• Converts your articles into ActivityPub posts that people can see on Mastodon
• Sends you back interactions (likes, boosts, replies) via the Webmention protocol

Pretty neat. You keep your content on your own server, and the Fediverse comes to fetch it.

What the plugin does

The grav-plugin-bridgyfed plugin handles the entire integration:

Microformats2 injection — Bridgy Fed needs to understand your page structure. The plugin automatically adds h-card, h-entry, p-author classes, etc. to your HTML. You don't need to touch your templates.

Well-known redirects — For the Fediverse to discover you, you need to respond to certain requests (/.well-known/webfinger, /.well-known/host-meta...). The plugin redirects all of that to Bridgy Fed.

Webmention sending — When you publish an article and check "Publish to Fediverse", the plugin sends a notification to Bridgy Fed.

Reception and display — When someone interacts with your post, Bridgy Fed sends a Webmention to your blog. The plugin stores it and displays it at the bottom of the article (likes, boosts, replies with avatars). You can see a concrete example on my test article which displays interactions received from the Fediverse.

How it works in practice

When I publish an article

My Grav article
      │
      ▼
Bridgy Fed Plugin (outgoing Webmention)
      │
      ▼
fed.brid.gy receives the notification
      │
      ▼
Bridgy Fed reads my article (thanks to Microformats)
      │
      ▼
ActivityPub post creation
      │
      ▼
Visible on Mastodon, Bluesky, etc.

When someone replies

Mastodon user replies/likes/boosts
      │
      ▼
Mastodon instance notifies Bridgy Fed
      │
      ▼
Bridgy Fed sends me a Webmention
      │
      ▼
My plugin receives and stores the interaction
      │
      ▼
Display on the article (facepile, comments)

It's elegant. Everything goes through open standards (ActivityPub, Webmention, Microformats2), and my blog remains the central point.

Installation and configuration

Step 1: Create your Bridgy Fed account

Go to fed.brid.gy and enter your site URL. Bridgy Fed will verify that you own it (via a link on your homepage or well-known redirects).

Once validated, you'll have a Fediverse identity like @yourdomain.com@yourdomain.com. People can search for you and follow you from Mastodon.

Step 2: Install the plugin

cd user/plugins
git clone https://github.com/ndieschburg/grav_plugin_bridgyfed.git bridgyfed
cd bridgyfed
composer install

Then enable it in Grav admin (Plugins > Bridgy Fed).

Step 3: Configure

In the admin, configure at minimum:

• Your name and profile picture — Important for Fediverse display
• Article templates — Default: item, blog-item, post

On the article side, a new "Fediverse" tab appears in the editor. Check "Publish to Fediverse" and save.

The struggles (because there were some)

As the old saying goes: "you see the blacksmith at the foot of the wall" (a French mixed proverb). And I hit a few walls.

Problem 1: Nobody could follow me

After configuring everything, I tried to follow myself from my Mastodon account. Error. I asked friends to test. Same thing. Impossible to subscribe to my Bridgy Fed profile.

The tricky part is that without followers, your articles aren't distributed to anyone. Fediverse instances only download posts if at least one of their users follows the author. So I had a blog connected to the Fediverse... talking to the void.

I contacted Ryan Barrett (Bridgy Fed's developer) on GitHub. He identified a bug in the handling of certain domains. A few days later, it was fixed. Thanks Ryan!

Problem 2: My interactions never arrived

Once the following was fixed, I tested: I liked my own articles from Mastodon, I replied, I boosted. Nothing. Nada. Not a single Webmention back.

Same drill, I contacted Ryan. After investigation, he pointed me to the docs: interactions from users without a profile picture are ignored. It was written in black and white in Bridgy Fed's documentation. I had just missed that detail.

My test Mastodon account didn't have an avatar. Once I added a photo, everything worked. Sindjeu (Belgian expletive), I should have read the docs more carefully...

Conclusion

The plugin is functional and available on GitHub: grav-plugin-bridgyfed.

It's open source, so if you use Grav and the Fediverse tempts you, feel free to try it. Issues and PRs are welcome.

Hoping this helps someone struggling with the same idea. By the way, if you also want to control your Grav blog with Claude, check out my MCP plugin. And if you follow me from Mastodon... well thanks, that makes at least 5 people now!

This article was originally written in French. This translation was generated automatically with AI assistance.