punkfairie.net

indieweb comments with webmentions

You may have noticed a small section at the bottom of diary pages for webmentions. If you’ve ever heard of pingbacks during the Wordpress days, they are the same concept!

Webmentions can be set up for any website, and displayed however you please. You can even pull fediverse comments as webmentions and display them on your site! I am not an expert, but following is a little tutorial on how I set up webmentions for this site.

I use 11ty to build my site, and you will often see tutorials that use 11ty data files to pull mentions at build time. The downside to this is that you have to rebuild your site every time you want to update your mentions. The solution to this is usually webhooks that tell netlify/vercel/what-have-you to re-deploy the site when new mentions are received, or scheduling a rebuild once a day. To me, this is unnecessarily complicated for the (imo) small gain of less client side javascript. Especially considering I self host my site using Docker on a server in my own home, and therefore can’t as easily use webhooks/scheduled rebuilds.

So I have instead taken the route of using client-side JS for this. Webmentions are updated on every page refresh, and if the user has JS turned off, no big loss for them. Comments are a progressive enhancement for this sort of website anyway. Another plus is that this tutorial should be applicable no matter how you make your website, as long as you have access to JS :)

Step 1: Webmention.io & Bridgy

I do not love using third party services for this, but the DIY way is way more complicated then I want to maintain, so I had to give in here.

Webmention.io the service that allows us to receive webmentions. You will need to have a website already published with web sign-in enabled (more on that below). Don’t forget to click the link to add a site after you are logged in!
Bridgy - this is optional, it allows for pulling in fedi/reddit/bluesky comments as webmentions.

If you don’t have web sign-in already enabled, here’s how to do so:

First - you need to have a website you can publish BEFORE setting up webmentions, as you will need at least a published index page with the html explained below in order to log into webmention.io. It doesn’t need to have content or be pretty, just accessible.

Put at least one of the following link tags between <head> and </head> on your index page. It MUST be on your index for sign-in to work!

<!-- sign in using OTP sent to your email: -->
<link href="mailto:YOUR@EMAIL.COM" rel="me" />

<!-- or use your github account: -->
<link href="https://github.com/YOUR_USERNAME" rel="me" />

It is possible to use your phone number as well, but I do not recommend this as <head> content is still visible to the public via the browser inspector, and to any web scrapers.

Publish your website with those changes, and then you should be able to go to webmention.io and log in with your email’d OTP or GitHub. Once you are on the dashboard, click the link to add a site and add in your website.

Step 2: Add your webmention link

We will add two things in this section: a <link> tag for bots, and a visible link for humans, letting them know how to send you webmentions.

On webmention.io, click “Sites” in the top bar, then click “Get Setup Code” next to your site (I somehow ended up with duplicate punkfairie.net entries - if that happens to you just pick the first one). Copy the code to somewhere between <head> and </head> on every page someone might want to send mentions for. If your site uses a global layout file, that’s a great place for it, otherwise you’ll have to paste it on every page you want mentions for.

Next, we will put a link on every page you want to receive mentions for, so that people can send you mentions. This part is not strictly necessary, as users could still send you mentions by using inspect element and finding the <link> element we just added, or using other automated tools. But it’s a better user experience to explicitly let people know you can receive mentions!

There are many ways to do this, but what I’ve done is probably the easiest. Going back to that code snippet we copied from webmention.io earlier, grab just the URL in the href="" part of that. If you go to that link in your browser, you’ll notice that it actually links to a form to send the mention with. Go ahead and put a link to that somewhere on each page you want to receive mentions for. I’ve done it like this (see it in action at the bottom of this page!):

<p>
  Have you linked to this page on your website?
  <a href="https://webmention.io/punkfairie.net/webmention"
    >Send me a webmention!</a
  >
</p>

Step 3: Display Webmentions

Now for the slightly more complicated bit. Receiving webmentions is fine and all, but they are useless unless displayed somehow!

I use Alpine.js for all my JS - if you’ve ever used jQuery it’s sort of trying to achieve the same goal. It makes it really easy to incorporate small amounts of interactivity. The actual fetch mentions logic is vanilla JS, so you can use that and figure out the displaying bit on your own! It isn’t much more complicated, but since I use Alpine that’s the method I’ll show here.

The easiest way to show this is by showing the full code (stripped of my own CSS classes) with comments explaining each piece. I’m not going to fully explain the Alpine.js bits, as that’s a whole other tutorial, but the docs are pretty easy to understand :)

This is the HTML that goes where you want the mentions to show:

<!--
  x-data lets Alpine.js know that it should use the
  'mentionList' code defined below to populate the mentions
-->
<div x-data="mentionList">
  <!-- If we got an error, don't render this -->
  <template x-if="!error">
    <!--
      A for loop - for each mention, render
      the contents of this <template>
    -->
    <template x-for="mention in mentions">
      <!--
        If we have the author name, use
        that. Otherwise 'Someone'
      -->
      <span x-text="mention.author.name || 'Someone'"></span>

      <!--
        link to the URL that your page was mentioned
          on, and make the link text the type of mention,
        using the function defined in the JS below
      -->
      <a :href="mention.url" x-text="getType(mention)"></a>

      <!--
        Date the mention was sent, again
        using a function defined below
      -->
      this post on <span x-text="getDate(mention)"></span>

      <!--
        If the mention contains text
        (i.e. a mastondon comment), display that
      -->
      <template x-if="mention.content.text">
        <!--
          The getText function is defined below,
          it just truncates long text
        -->
        <blockquote x-text="getText(mention)"></blockquote>
      </template>
    </template>
  </template>
</div>

And this is the javascript that needs to be on the same page as the HTML code above, after <body> and ideally as close to </body> as possible¹:

<script>
  // The API endpoint to get mentions for this page.
  // Replace punkfairie.net/page-to-get with the URL
  // of the page you want to get mentions for.
  //
  // If you are using 11ty and a template language, you can
  // insert the link automatically like this (example
  // using liquid):
  // target=https://punkfairie.net/{{ permalink }}

  const url =
    'https://webmention.io/api/mentions.jf2?target=https://punkfairie.net/your-page&sort-by=published';

  document.addEventListener('alpine:init', () => {
    //
    // This is the bit that actually grabs the
    // mentions. 'mentionList' is what we put in the
    // x-data attribute in the HTML above.
    Alpine.data('mentionList', () => ({
      //
      // This runs on page load/refresh.
      async init() {
        //
        // try { ... } catch { ... } gracefully
        // handles errors.
        try {
          const response = await fetch(url);

          // If we got, say, a 404 error, set
          // error to true so that the HTML
          // above wouldn't try to render.
          if (!response.ok) {
            this.error = true;
          }

          // Set our 'mentions' variable to the
          // fetched mention list.
          const result = await response.json();
          this.mentions = result.children;
        } catch (err) {
          //
          // If fetch() threw an error, prevent the
          // HTML from loading.
          this.error = true;
        }
      },

      // Initial values for our variables.
      // Despite being below init(), these are
      // actually set first and available to init().
      mentions: [],
      error: false,

      // The webmention.io API returns the type of
      // mention in a way that isn't as nice to display,
      // so we transform that into something better.
      getType(mention) {
        switch (mention['wm-property']) {
          case 'like-of':
            return 'liked';
            break;
          case 'bookmark-of':
            return 'bookmarked';
            break;
          case 'repost-of':
            return 'reposted';
            break;
          case 'in-reply-to':
            return 'replied to';
            break;
          default:
            return 'mentioned';
        }
      },

      // This function just truncates long comment
      // text to a max of 200 chars.
      getText(mention) {
        const len = 200;
        const text = mention.content.text;

        if (text.length <= len) {
          return text;
        } else {
          return text.slice(0, len) + '...';
        }
      },

      // This function formats dates in a prettier way.
      getDate(mention) {
        //
        // Use the published date if it's available,
        // otherwise use the received date.
        const date = new Date(mention.published || mention['wm-received']);

        const formatter = new Intl.DateTimeFormat(undefined, {
          dateStyle: 'medium',
          timeStyle: 'short',
        });

        return formatter.format(date);
      },
    }));
  });
</script>

If you are using something like 11ty & a template language (such as liquid or nunjucks) that supports includes, you can put the displaying webmentions code in a separate file and include it on all your pages, to reduce copy pasting! Just make sure you use something like the {{ permalink }} shortcode to change the JS url variable on each page.

And that’s all you need! The rest of this is optional, but goes over setting up fedi connections.

Step 4: Connecting Socials

This is where Bridgy will come in! Go ahead and click the social media option you want to connect (you can connect multiple!). If it asks “What do you want to do?” choose the first option: “Cross-post to a Mastodon account” (the rest of these instructions assume you are connecting Mastodon, as that’s what I use).

You will also want to have a link to your website in your Mastodon profile. You can even “verify” yourself by adding a rel="me" link on your website that links to your Mastodon profile! Just add the following between <head> and </head>:

<link href="https://YOUR.INSTANCE/@YOUR_USERNAME" rel="me" />

punkfairie.net yearly roundup

It seems we’re doing yearly updates here, oops! I swear I did mean to post more often when I came up with this section haha.

I’ve fixed some things, there’s a new chat box I’m sure you noticed on the home page. CBox has needed replacing for a decade now and I’ve finally got Chattable working. Dates on the diary index page are fixed as well (due to the way diary post pages are built, 11ty was setting the last site deploy date as the date for every single post, instead of when they were actually written!). Also the url for diary posts is simplified, in case anyone notices that sort of thing.

Epiphany & Somethin’ Funny are back online! I’ve been breeding a bit in Petz 4 again :) I have a beautiful Windows XP laptop for all my P.F. Magic games!

The web servers mentioned in my last update are up and running! All my websites are running on my servers, plus my git forge. Wife also has a mastodon server & blog on her own server!

On a personal note, I got married in September!!! The wedding went off with barely a hitch and went way too fast. I can’t recommend planning a wedding, but the party almost made it worth it LOL.

It's been a while (what I've been up to)

punkfairie.net moved registrars. I was loyal to NameSilo for probably close to 10 years! But as prices started to creep up, they were no longer the cheapest option on the market. porkbun is now the winner in that category, and as an added bonus the feature set is wayyy less bloated which makes the UI super clean and easy to navigate. More features are not always better!

I’m still ironing out DNS migration, so the links to saudade and epiphany don’t work at the moment. Fixed soon I hope!

Also, I may be moving off Neocities soon. Fiancee has a neat little homelab set up and has promised me a little server of my own (who I’ve named ‘MarleyNet’!). Some sort of load balancer has to be set up though to tell the difference between traffic to blackcat.vip (fiancee’s domain) and punkfairie.net. So that may take some time.

Future plans for MarleyNet beyond this site:

A Gitea instance.
Caddy as the web server.

MarleyNet has an older sister, MarleyCentre (named after the hardware: ThinkCentre). Currently all she’s running is a Soft Serve instance, accessible from a Wishlist directory.

Other tech projects

I became an arch user. And a vim user. I completely ditched Windows a while ago and for the most part have been happy with that decision! I still can’t get Skyrim to load with a Wabbajack modlist and my Farming Simulator accessories don’t work right but those are the only downsides so far. It’s been a lot of fun tinkering with my own system :)

Neovim is mostly going fine, still got some tinkering to do for everything to work how I want it to for editing this site. But it’s absolutely perfect for editing configs & shell scripts, which I find myself doing a lot of these days. I even learned Go with it!!

The Neovim config I’m using is LazyVim, but if you’re a beginner I don’t recommend installing someone else’s config first. Just start using it, and add things to your own config as you go. Once you get into plugins, and get sick of managing conflicts and plugin opts on your own, then install LazyVim :). It’s super customizable, and most things just work.

What I’m up to elsewhere

I’ve gotten really into Obsidian lately, and the whole second brain/personal knowledge management thing in general. I may do a proper writeup about it soon with some links!

I got a new job recently, doing admin work which means NO MORE CUSTOMER SERVICE!! I’m absolutely loving it so far, and it’s what got me into Obsidian and everything mentioned above, because there’s just so much random information I need to know and processes to follow and I needed some way to keep track of it all. Plus my day is way more self-structured than before, and there’s a lot of random little to-dos to keep track of!

Moving to Neocities

Finished the new rainbow layout today! I’m moving the site to Neocities for the social aspect, and because PHP isn’t allowed there I switched over to Eleventy - a static site compiler.

I redid the layout from the ground up with the intention of making it mobile friendly, but it’s not a priority and I’m not even going to look at what the site looks like on mobile lol.

🏳️‍⚧️🏳️‍🌈 Happy pride 🏳️‍🌈🏳️‍⚧️