The notes of bnijenhuis

Adding Prettier in Eleventy using Transforms

2025-02-02T00:00:00Z

Recently I decided to look into some functionality in Eleventy I hadn't used before: Transforms. According to their website:

Transforms can modify a template’s output. For example, use a transform to format/prettify an HTML file with proper whitespace.

So let's try and use this functionality to have nicely formatted HTML by using Prettier. Prettier is a code formatter that can be used for a variety of languages and is customizable to your own preferences.

Added Prettier to the Eleventy config

Before using Prettier in Eleventy it needs to be installed. It's pretty (no pun intended) self-explanatory when visiting their docs: https://prettier.io/docs/install/. After installing you'll be able to use it in your Eleventy project. Go to your Eleventy config file and add the require statement for Prettier:

const prettier = require("prettier");

Next up, add the transform to the module.exports as follows:

eleventyConfig.addTransform("prettier", function (content) {
    if ((this.page.outputPath || "").endsWith(".html")) {

        let prettified = prettier.format(content, {
            bracketSameLine: true,
            printWidth: 512,
            parser: "html",
            tabWidth: 2
        });
        return prettified;
    }

    // If not an HTML output, return content as-is
    return content;
});

This code will add the prettier transform, which handles all the content. It checks if the output path ends with .html, because we only want to format the HTML pages. If it's a HTML page, format the content of the page with whatever Prettier settings you prefer and return the pretty content. For all other content, don't do anything and return it as-is.

The settings I use are:

bracketSameLine: true: Put the > of a multi-line HTML (HTML, JSX, Vue, Angular) element at the end of the last line instead of being alone on the next line (does not apply to self closing elements). I find it much easier to read when the closing > is on the same line;
printWidth: 512: Specify the line length that the printer will wrap on. Although they recommend a much lower value than I use, I have some inline SVG's that are much larger. Breaking them up makes it harder to read the code, so I've chosen to use a large value;
parser: "html": Specify which parser to use. Prettier has a lot of parsers, but because I'm currently only using it to make the HTML pretty I use the "html" parser;
tabWidth: 2: Specify the number of spaces per indentation-level. Again, this is just a setting I prefer. I switched between 2 and 4, but I find there's too much white space when using a tab width of 4 spaces. I realise it's set to the default now and I could leave it out, but I might just switch it again later on, so I just leave it in for now.

That's all there is to it. Running your Eleventy build will now have ✨pretty✨ HTML pages!

User friendly dark mode

2024-10-14T00:00:00Z

This website is implemented with a very minimal style, with black text on a white background. High contrast, easy to read, no distractions. But opening the website when you're in a darker environment is like accidentally turning on a flashlight right in your face. Let's do something about this.

Preferred color scheme

I'm sure you've heard of dark mode before, and a lot of websites have implemented functionality to switch between dark mode and light mode. But before we dive into that functionality, let's handle the system settings first. A user can set their preference for a dark or light mode in their operating system. This affects, among many other things, how the browser UI is shown. We can tap into this preference in CSS via the preferred color scheme media query. To do this we need to define some default colors as CSS variables and override these colors with the media query. Most of the time developers use the light mode of the website as the default style and overwrite these values for users that prefer a dark color scheme. So for this website the implementation would be something like the following:

:root {
    --text-color: black;
    --bg-color: white;
}

@media (prefers-color-scheme: dark) {
    :root {
        --text-color: white;
        --bg-color: black;
    }
}

html {
    color: var(--text-color);
    background-color: var(--bg-color);
    color-scheme: light dark;
}

I've added the color-scheme property to the html selector as well, which indicates that the website supports both light and dark mode. This will change the default colors of interaction UI, form controls and some other things. So if there's no style provided for those specific elements, the color-scheme property will handle these nicely for light and dark mode.

Let the user choose

Even though we're respecting the system settings now, there's no way for the user to set the preference for this website alone. The user might have their system set to dark mode, but might prefer your website in light mode. Or the other way around.

To provide this service to the user, we need to cater for 3 states:

System preference;
Dark mode;
Light mode.

Determine the markup

The best implementation would be a tri-state button, but unfortunately there's no such thing. Using radio buttons would be a nice solution, but as Hidde de Vries mentioned in his dark mode article that isn't really intuitive for keyboard users (and I agree). So what then?

There are a lot of different implementations, and all of them have their own pros and cons, but I'm going for a button implementation. I don't want 1 toggle button, because I want the 3 options mentioned above and not just a toggle between dark and light mode. Thse buttons need to be grouped together, so to do this we need to add a fieldset around them with a legend to label the group. Combined with the aria-pressed attribute to indicate which button is selected, we get something like this:

<div class="themes" hidden>
    <fieldset>
        <legend>Themes</legend>
        <button aria-pressed="false" data-theme="system">System preference</button>
        <button aria-pressed="false" data-theme="light">Light mode</button>
        <button aria-pressed="false" data-theme="dark">Dark mode</button>
    </fieldset>
</div>

Now because this functionality will only work with JavaScript, we have to show this only when JavaScript is enabled. That's why I've added a div with the hidden attribute so it's hidden by default, and using JavaScript we're going to remove that hidden attribute. Another way would be to add all the HTML via JavaScript, but I find this way a bit more maintainable and readable.

Adding the functionality

There will be a few steps that need to be done to complete the functionality:

Show markup of the functionality;
Handle selected theme.

Show markup of the functionality

As I've mentioned before, I've hidden the markup by default, so we need to show this first by removing the hidden attribute:

document.querySelector('.themes').removeAttribute('hidden');

Handle selected theme

Now that the markup is visible we can handle the buttons. We're going to save the selected theme in localStorage, make sure the clicked button is selected while the other buttons are not and add a class to the <html> for the selected theme while removing any other themes from the <html> classes. The code for all of this will be something like this (with comments to explain):

// get the selected theme from localStorage and fallback to system
let theme = (localStorage.getItem('theme')) ? localStorage.getItem('theme'): 'system';

// set selected button
document.querySelector('.themes button[data-theme="' + theme + '"]').setAttribute('aria-pressed', 'true');

// get theme buttons
let themeButtons = document.querySelectorAll('.themes button');

// handle click on button
themeButtons.forEach((themeButton) => {
    themeButton.addEventListener('click', (event) => {

        // get selected theme
        let selectedTheme = themeButton.getAttribute('data-theme');

        // save selected theme to localStorage
        localStorage.setItem('theme', selectedTheme);
        
        // add pressed state to button
        themeButton.setAttribute('aria-pressed', 'true');

        // add class to html so we can handle theme in css
        document.querySelector('html').classList.add('theme-' + selectedTheme);

        // make sure other buttons and themes aren't selected
        themeButtons.forEach((otherThemeButton) => {

            // button does not match selected button
            if (themeButton != otherThemeButton) {
            
                // remove pressed state of button
                otherThemeButton.setAttribute('aria-pressed', 'false');

                // remove possible themes from html
                document.querySelector('html').classList.remove('theme-' + otherThemeButton.getAttribute('data-theme'));
                
            }

        });
    });
});

What's left is to handle the selected theme on pageload. We've already checked localStorage for the saved theme in the code we just wrote, and we already add the theme class to the <html> when we click one of the buttons, but we're not setting the right theme on pageload yet. So we need these two lines of code we wrote earlier:

let theme = (localStorage.getItem('theme')) ? localStorage.getItem('theme'): 'system';
document.querySelector('html').classList.add('theme-' + theme);

Make sure to place these two lines in a <script> block in the <head>, right before loading the stylesheet to prevent flickering. Because if you do it later on, the style is loaded first, you then change the theme, which might cause a change from light to dark mode (or the other way around).

Don't forget the favicon

If the user has their operating system preferences set to dark mode, the browser UI will be dark. If your favicon happens to be dark as well, it could be that it's not recognizable anymore (which is the whole point of the favicon). There is a solution for that (well, for most browsers, that is): SVG favicons. Because SVG favicons can contain CSS and, more importantly, media queries, which allows us to do something similar to what we did earlier to handle the operating system preference in our website. Together with the code of the SVG, we get something like this:

<svg viewBox="0 0 128 128" xmlns="http://www.w3.org/2000/svg">
	<style>
		path { fill: #000000; }
    	@media (prefers-color-scheme: dark) {
			path { fill: #ffffff; }
    	}
	</style>
	<path d="M5.714 44.034c-.99-.849-.99-3.82.283-8.772 1.274-4.951 2.547-8.347 4.103-9.903.99-.99 3.537-1.556 7.782-1.556 7.498 0 12.591.848 15.42 2.405.991.707 1.557 3.537 1.557 8.347 0 1.415 0 3.254-.141 5.66-.142 2.404-.142 4.244-.142 5.517 0 1.273.142 2.122.283 2.405.283.283.99.142 2.264-.424 1.132-.566 2.83-1.274 4.952-1.981 2.122-.707 4.385-.99 6.65-.707 4.95.565 8.77 3.395 11.459 8.488 2.547 5.094 3.82 11.743 3.82 19.808 0 2.688-.141 4.81-.283 6.225-.707 6.932-2.688 12.591-5.942 16.977-3.396 4.386-7.64 6.791-12.875 7.499l-3.254.141c-2.264 0-4.386-.283-6.508-.707-2.122-.566-3.82-1.132-5.376-1.84-1.698-.707-2.405-.99-2.547-.99-.99-.424-1.98-.707-2.97-.566-.991.142-1.84.708-2.548 1.981-.424.99-2.546 1.132-6.083.283-3.679-.707-5.8-1.556-6.225-2.688-.142-.283-.283-1.556-.283-3.962 0-3.112.141-8.488.566-16.27.283-7.781.566-14.572.707-20.656.142-5.942.142-9.196 0-9.904-.141-.565-.283-1.131-.707-1.697l-1.132-1.132c-.283-.283-.85-.708-1.556-1.132-.708-.424-1.132-.707-1.274-.849zm27.589 37.21c2.405.424 4.244.14 6.225-.85 1.415-.99 2.83-2.263 3.678-4.102 1.415-3.679.566-6.367-2.83-7.923-.848-.425-1.838-.566-2.829-.142-1.415.425-2.263 2.688-3.254 6.65-1.415 3.961-1.415 6.083-.99 6.366z" />
	<path d="M61.174 84.356c.708-.707 1.698-1.273 3.254-1.698 1.415-.424 2.264-1.132 2.406-1.839.141-.849.424-1.84.707-3.113.141-1.131.283-1.98.424-2.688.142-.566.283-1.273.425-2.122.141-.707.141-1.415.283-1.84v-1.414c-.142-.424-.142-.849-.283-1.132-.142-.283-.283-.566-.566-.707-.566-.425-1.415-.85-2.405-1.274-.99-.424-1.84-.848-2.264-1.273-.424-.283-.849-.849-1.273-1.698-.425-.707-.566-1.697-.566-2.97 0-2.83.566-6.084 1.556-9.621.99-3.537 2.264-5.801 3.679-6.791 1.131-.708 3.961-1.132 8.63-1.132 7.781 0 12.309.707 13.299 1.98.566.85.707 3.113.424 6.65-.141 1.556.142 2.405.708 2.264.566-.142 1.273-.708 2.264-1.98.99-1.274 2.263-2.548 4.102-3.962 1.84-1.415 3.82-2.406 6.226-2.971 1.697-.425 2.97-.566 3.82-.566 3.537 0 6.79 1.273 9.479 3.82 2.688 2.546 4.244 6.083 4.669 10.47a32.94 32.94 0 01-.566 9.761c-.708 3.537-1.415 6.225-1.981 8.348-.566 2.122-.566 3.678-.142 4.527.283.424 1.132 1.132 2.406 1.98 1.273.85 2.263 1.698 2.688 2.689.707 1.273.424 3.82-.566 7.64-1.132 3.961-2.405 6.65-3.679 7.923-1.273 1.273-4.951 1.98-11.035 1.98-8.206 0-10.611-.849-11.177-2.546-.424-1.415-.566-5.235-.566-11.319 0-2.405 0-5.8.142-10.045v-7.781c0-.99-2.264-1.274-2.83-.85-.707.425-1.273 1.699-1.556 3.538-.142 2.122-.283 4.81-.142 8.064.142 3.254 0 6.933-.141 10.611-.142 3.82-.566 6.367-1.274 7.357-1.131 2.122-5.942 3.113-14.29 3.113-5.517 0-9.054-.566-10.327-1.84-1.273-1.131-2.547-4.102-3.82-8.913-1.132-4.669-1.132-7.64-.142-8.63z" />
</svg>

This will set the fill of the path to black, but if the user prefers a dark color scheme (and thus has a dark browser UI) it changes the fill of the path to white.

Finetuning contrast colors

Lastly I've changed the color codes for black and white on this website to be a little easier on the eyes. I'm not a designer (no shit), but this comment on StackExchange sums it up pretty well with multiple references (if you're interested). In short it states that although high contrast is good, too high of a contrast could be straining on the eyes. So for dark mode I've changed the black to #1f2020 and the white to #e2e2e2 and for light mode I've changed the black to #1f2020 and the white to #f8f7f3, which makes a bit easier on the eyes.

Updating Eleventy...and more

2024-09-11T00:00:00Z

As you might have noticed, I don't have a very stable streak in posting notes on here. It only took almost a year between my last note and the one before that, so my setup tends to get outdated. And because I take so long, I keep forgetting what and how I need to update everything. So to make it easier for my future self I decided to document it.

Update `npm` first

Last time I already received a notice in terminal that my npm version has a new major version available, so let's start with updating this. The notice already gave the command to update npm, in this case it was:

npm install -g npm@10.8.3

And as usual, this returned a bunch of permission errors, because I forgot I need to install this as the root user, so let's try again:

sudo npm install -g npm@10.8.3

That command solved the permissions errors, but returned a new error:

npm WARN EBADENGINE Unsupported engine {
npm WARN EBADENGINE   package: 'npm@10.8.3',
npm WARN EBADENGINE   required: { node: '^18.17.0 || >=20.5.0' },
npm WARN EBADENGINE   current: { node: 'v13.7.0', npm: '7.8.0' }
npm WARN EBADENGINE }

No wait, update `Node.js` first

My Node.js version appears to be in need of an update. There are several ways of doing this, so I just go for the easiest one, which is downloading and installing it. After restarting the terminal to make sure the changes to take effect I double check the installation by seeing which Node.js version is installed now:

node -v

This returned v20.17.0, so Node.js is now up to date.

NOW update `npm`

Node.js is updated to the right version so updating npm should work now, so let's try again:

sudo npm install -g npm@10.8.3

No errors return, so could it be that npm is actually updated? Let's check:

npm -v

Success! The installed version of npm is now 10.8.3.

Next up: update Eleventy

On to the actual purpose of this exercise: updating Eleventy. First check which version is installed:

npx @11ty/eleventy --version

Turns out I'm running version 1.0.1, which is pretty old, because Eleventy is currently on version 2.0.1 (that is the latest stable version, but 3.0.0 is already in beta at the time of writing). There's some excellent documentation on their website on how to do this and there's even an upgrade helper to check your project after the upgrade. Nothing left to do than to follow these steps.

Since I use as little dependencies as possible in my setup, I didn't run into any problems when upgrading Eleventy from v1 to v2. That means I'm done and Eleventy is now updated to 2.0.1!

Minimize CLS caused by font loading

2024-09-05T00:00:00Z

As you might have noticed, the style of this website is pretty minimal. And because it's so minimal there's not much that could hurt the lighthouse score...or so you'd think. Turns out that the one thing I did do already hurts the score: loading a web font.

Every once in a while I check the scores of my website to see if things are still working correctly, and I noticed that on mobile the performance score dropped to 97. Although still good, it should be 100 for such a simple layout. The cause of it was the Cumulative Layout Shift (or CLS). The difference between the webfont (Asap) and the fallback font (Arial) caused the layout to shift a bit while loading. In particular the character widths that are different enough to cause the line breaks to be at different places in the paragraphs.

So it's clear what the problem is, but how can we solve it? Well, by creating a new fallback font that has matching character widths. The key however is to use a web-safe font. A web-safe font is a font that's already assumed to be on the majority of users' devices, so there's no need to download the font. The fallback font is nothing more than a tweaked web-safe font. There are several tools available to do this, like Fallback Font Generator, but i prefer to use Automatic font matching. You just choose your font (make sure to have it installed on your system) and it will automatically generate a fallback font that matches your font as best as possible.

What's left to do is to add the fallback font to your stylesheet by copying the code given to you, in this case:

@font-face {
    font-family: 'Asap-fallback';
    size-adjust: 98.3%;
    ascent-override: 91%;
    src: local('Arial');
}

and add it as a fallback:

font-family: Asap, 'Asap-fallback', Arial, sans-serif;

To top it all off I added my webfont as a preload as well by adding it to the <head> like this:

<link rel="preload" href="/fonts/Asap-VariableFont_wght.woff2" as="font" type="font/woff2" crossorigin>

For more information about this I suggest you read this short article that goes into the different attributes that are used.

By making these two changes I've improved the performance score in lighthouse back to a nice 100...until they decide to change the metrics again.

Add verified links to your Mastodon profile

2022-11-21T00:00:00Z

Recently I, among a whole lot of others, revived my Mastodon account now that a spoiled brat took over Twitter and is currently burning it to the ground. Along with the revival I started searching for the people I'd like to follow and I saw several accounts that had verified links on their profile. Now with Twitter it would be a real hassle to get a verified account (and it got even weirder with paid blue ticks, official ticks, etc.). On Mastodon you don't have verified accounts, but as it turned out you can add verified links to your profile.

On Mastodon you get 4 fields to add meta data to your profile. You can use it for whatever you'd like, but most people use at least one to add their website. Mastodon even added a block on how you can verify yourself as the owner of the link. All you have to do is add a reference to your Mastodon profile including a rel="me" attribute. This can be a link (like I've used on my website), but it can also be a meta tag in the head of the website, as long it includes the rel="me" attribute.

But there is a little catch, and (luckily for me) Paul had the answer^[1]. Do not, I repeat, do not add a trailing slash to your website. For whatever reason it won't verify the link if you add the website to your profile with a trailing slash.

That's it. I couldn't figure this out myself, and I couldn't find any documentation about it. But apparently it works.

^[1] Dutch toot where Paul suggests to remove the trailing slash.

Changing urls but keeping webmentions in Eleventy

2022-11-03T00:00:00Z

I started out creating these notes with the date in the url, because I thought it was an easy way to keep some overview of my notes. But it turned out to be rather annoying when I was creating new posts. I rarely start and finish a post on the same day, which meant I would have to change the filename multiple times. It also meant that every url was 10 characters longer than it needed to be. So I've decided to change it, because the date will always be in the post itself anyway. Also, Hidde did it, so it must be the right thing to do ;).

The thing is, I've setup webmentions to add some interaction to my notes (as you can read in my note Implementing clientside webmentions). And some of my notes got some decent traction, so I'd like to keep the webmentions I've had thus far, but changing the urls would mean I would lose them. The solution to this was even simpler than I thought when I was looking at the webmentions API. Turns out you can request the webmentions for multiple targets at once.

For example, to get the webmentions of my first note I'm calling this url:

https://webmention.io/api/mentions.jf2?target=https://bnijenhuis.nl/notes/2021-03-01-unhurried-development/

The new url (without the date) would be https://bnijenhuis.nl/notes/unhurried-development/, so we need to add this url as a target while getting the webmentions (and turn the target parameter into an array), which would result in:

https://webmention.io/api/mentions.jf2?target[]=https://bnijenhuis.nl/notes/2021-03-01-unhurried-development/&target[]=https://bnijenhuis.nl/notes/unhurried-development/

But how do we get the old url?

This too was pretty simple to do in Eleventy. You can define your own frontmatter variables, which means I could define the old url here (I named it aliasUrl). For example, the frontmatter of my first note would become:

---
pageTitle: 'Unhurried Development'
date: 2021-03-01
aliasUrl: '/notes/2021-03-01-unhurried-development/'
tags:
 - notes
---

The webmentions functionality can access this variable and therefor we can add it as a target. And that's all there is to it. Add a variable to the frontmatter and use this while getting the webmentions.

Setting up a local development environment

2022-10-17T00:00:00Z

Full disclosure: I'm writing this mainly because I keep having to look up how I've set up my development environment. I'm happy with how it's set up, but because I use it for some hobby projects and the occasional client work, I keep forgetting how I have to set up a new project. Time to document it for my own reference (in case the reference articles disappear for some reason) and while I'm at it I might as well share it with the rest of you.

There are two detailed posts by Tania Rascia that I've used for my setup:

I recommend you read these articles for more background information and/or how to set up the development environment on Windows. I'll go over the parts I've used to set it up on my Mac. Again, to set it up on Windows, check out the articles of Tania.

Local server environment

There are different ways to set up a local server environment, but I find the easiest way to do this is by using MAMP. This allows you to run Apache, MySQL and PHP with ease. You can even choose if you want to run Apache or Nginx, and you can choose which PHP version you want to run on your local server. Install it, open it, click on Start and you're good to go. If you want to run one project on http://localhost:8888 that is.

Virtual hosts

If you only want to run one project at once on localhost, you can stick with the setup MAMP has provided. You only have to change the Document root to your project and restart the server. I, however, prefer to run multiple projects on their own urls. Here's what you have to do to achieve this.

Enable virtual hosts in Apache

You only need to do this once. Open the apache config file located at /Applications/MAMP/conf/apache/httpd.conf and enable the following line (it's hashed out by default):

Include /Applications/MAMP/conf/apache/extra/httpd-vhosts.conf

Allow symlink override

This too has to be done only once. In the same apache config file, located at /Applications/MAMP/conf/apache/httpd.conf, change this:

<Directory />
    Options Indexes FollowSymLinks
    AllowOverride None
</Directory>

to this:

<Directory />
  Options Indexes FollowSymLinks
  AllowOverride All
</Directory>

Add virtual host config

Next up, you need to add the actual virtual host config. You need to do this for every project you want to run on a different url. Open the Apache vhost config file, located at /Applications/MAMP/conf/apache/extra/httpd-vhosts.conf. At the end of the file add the following for each project:

<VirtualHost *:80>
  ServerName myproject.test
  DocumentRoot "/Users/bnijenhuis/Sites/myproject"
</VirtualHost>

Enter the url you want to use for ServerName (do not use .dev however, because that's not supported anymore), and enter the location of the project for DocumentRoot.

Add project url to the `hosts` file

MAMP will now serve the projects at the urls you've provided in the virtual host config, but the browser won't recognize these urls yet. You have to add the project urls to the hosts file. Open your hosts file, located at /etc/hosts, and add your projects at the end of the file (each project on a new line) like this:

127.0.0.1   myproject.test

Remove the port from the url

We're almost there. The project is on the right url, served from the right folder, but it has a port number in the url. In this example it's myproject.test:8888, so we have to change that (this also has to be done once). Open the apache config file again, located at /Applications/MAMP/conf/apache/httpd.conf, and change the following lines:

Listen 8888
ServerName localhost:8888

to:

Listen 80
ServerName localhost:80

To make sure MAMP also listen to these ports, you need to change it's ports in Preferences:

Apache Port: 80
Nginx Port: 8888
MySQL Port: 3306

Now restart MAMP and we're done. You can now use multiple projects on their own urls on your computer.

Load file contents in Eleventy

2021-07-11T00:00:00Z

At the moment the only image on my website is my logo on the homepage. But since it's an SVG, I decided to load it directly in the HTML. I could just copy the contents of the SVG file and paste it where I wanted it. But if I decide to have the image at several different places, and I make some adjustment to it, I also would have to change it at several different places.

I don't want to do that, with the risk of forgetting one. So what I want to do is to keep the SVG file, and load the contents of it dynamically. This turned out to be easier than I thought.

const fs = require("fs");

eleventyConfig.addFilter('printFileContents', function(filePath) {
    const relativeFilePath = `.` + filePath;
    const fileContents = fs.readFileSync(relativeFilePath, (err, data) => {
        if (err) throw err;
        return data;
    });
    
    return fileContents.toString('utf8');
});

I've created a filter that takes the file path, finds the file, opens it and returns the contents. It requires the file system module, but I already had this loaded for automatically generate open graph images anyway.

To use this filter, just add it like you would use other filters:

{{ '/img/bnijenhuis.svg' | printFileContents }}

The result, in this case, is the full SVG code loaded in the HTML.

Implementing Service Workers with limited cache

2021-07-07T00:00:00Z

When I wrote the post about Implementing clientside webmentions a while ago it was mentioned by Nicolas Hoizey that this implementation would result in many requests to webmention.io. And although that's the result of having a static website with dynamic webmentions, I still wanted to try and optimize this. I was already planning on implementing service workers and this was the perfect use case.

What are service workers?

I kinda knew what service workers were, but not in detail. But of course there's a lot of information available about this. I watched the YouTube series by The Net Ninja, read The Offline Cookbook, one or two articles on Google's developers blog and documentation on MDN.

These sources will give you enough information to understand the fundamentals of service workers and what possibilities you're given as a developer.

What do I want to achieve?

As mentioned earlier the use case was to optimize the webmentions. But I had some other goals as well. The complete list was:

Serve core assets from service worker for speed purposes;
Make sure the cached core assets are up to date;
Cache webmention requests;
Create an offline fallback when there's no connection.

Let's do it

The first step is to set up the basics. These are extensively covered in all the documentation, so I won't go too deep into it.

Setting the variables

const version = '-v2';
const coreCacheName = 'core' + version;
const apiCacheName = 'api' + version;
const coreAssets = [
    '/',
    '/css/style.css',
    '/fonts/Asap-Italic-VariableFont_wght.woff2',
    '/fonts/Asap-VariableFont_wght.woff2',
    '/img/bnijenhuis.svg',
    '/favicon.ico',
    '/offline/',
    '/offline.json'
];
const localDomains = [
    'http://bnijenhuis-nl.test',
    'https://bnijenhuis.nl'
]

First I've defined some variables that are going to be used in the service worker. A version that is used in combination with the two cache names: coreCacheName (used for the core assets) and apiCacheName (used for the webmention requests). By using a version in the cache names you can remove old cache when you make changes to your service workers, so you can make sure the user has the right cache.

I've also defined a coreAssets array with, you guessed it, a list of all the core assets I wanted to cache. It also includes /offline/ and /offline.json which I'm going to explain later in this article.

Lastly I've defined an array of localDomains which I'm going to use later for checking what requests to cache.

Install the service worker

// install service worker and cache core assets
addEventListener('install', function (event) {
	event.waitUntil(
        caches.open(coreCacheName).then(function (cache) { 
            cache.addAll(coreAssets);
        })
    );
});

When installing the service worker I immediately make sure that the core assets are cached. Make sure that when using cache.addAll() all the assets are available. If one is missing, the service worker will fail to install.

Activating the service worker

// make sure to remove old caches
addEventListener('activate', function (event) {
    event.waitUntil(
        caches.keys().then(function (keys) { 
            return Promise.all(keys
                .filter(key => key !== coreCacheName && key !== apiCacheName)
                .map(key => caches.delete(key))
            )
        })
    )
});

The activate event listener will fire after the installation of the service worker. This also means it's called when the service worker is updated. And the service worker will update itself when something has been changed in it's file.

I want to make sure that old caches are removed when I update the version in the service worker. So in the activate event I loop through the available caches and if the cache name does not match with one of the two cache names I've already defined, I will delete this cache.

Handling the requests

So this is where all the good stuff happens. Every request that is made on the website will go through the fetch event. There are some handy tricks I'm using to meet the goals I've set earlier. Let's get into the code.


// fetch assets and serve from cache and update cache
addEventListener('fetch', function (event) {

    if (event.request.url.includes('/css/style.css')) {

        // (directly) respond with cached asset (if available)
        event.respondWith(serveFromCache(event, true, false));

        // update cache
        event.waitUntil(updateCache(event.request, coreCacheName));

    } else if (event.request.url.includes('https://webmention.io/api/')) {

        // we want to limit the requests to webmention.io
        // (directly) respond with cached asset (if available)
        event.respondWith(serveFromCache(event, false, true));

    } else {

        // (directly) respond with cached asset (if available)
        event.respondWith(serveFromCache(event, false, false));

        // update cache (only if in core assets)
        var requestUrl = event.request.url;
        for (const localDomain of localDomains) {
            requestUrl = requestUrl.replace(localDomain, '');
        }

        if (coreAssets.includes(requestUrl)) {
            event.waitUntil(updateCache(event.request, coreCacheName));
        }

    }
});

To make sure the code is still readable and to not repeat any code, I've moved some functionality to two other functions, serveFromCache() and updateCache(). I'll go into this later, but let's look at what's happening in this event listener.

First I'm checking which requests are made, because I want to handle some of them differently. If the request is for the CSS file I'll try and serve it from the cache and after the file is served I make sure the cache is updated.

If the request is for the webmentions I'll try and serve it from the cache, but I won't update the cache because I only want to update the cache once a day. More on this later on.

For all the other requests I'll try and serve it from cache, and if it's a core asset I make sure the cache is updated. The request url however contains the domain, so I strip my test domain and my live domain (set in the localDomains variable) from the request url to check if it's in my core asset array.

The `serveFromCache()` function

/**
 * serve request from cache
 * if file isn't cached longer than 24 hours, it's still valid
 * @param {Event} event the request event
 * @param {Boolean} ignoreSearch if true, ignore search parameters in request
 * @param {Boolean} checkExpiryHeader if true, check for custom expiry header
 * @return {Object} response object from cache or from fetch
 */
function serveFromCache(event, ignoreSearch, checkExpiryHeader) {

    // set the right match options
    var matchOptions = {};
    if (ignoreSearch) matchOptions = {ignoreSearch:true};

    return caches.match(event.request, matchOptions).then(function (cacheResponse) { 

        // if found return cache
        if (cacheResponse) {
            if (checkExpiryHeader) {
                if (isCacheResponseStillValid(cacheResponse)) {
                    return cacheResponse;
                }
            } else {
                return cacheResponse;
            }
        }
        
        // fetch it again, because cache was not found or was expired
        return fetch(event.request).then(function (response) {

            if (event.request.url.includes('/css/style.css')) {
                updateCache(event.request, coreCacheName);
            } else if (event.request.url.includes('https://webmention.io/api/')) {
                updateCache(event.request, apiCacheName);
            }

            return response;

        // if offline and not found in cache, return offline data
        }).catch(function (error) {

            if (event.request.url.endsWith('/')) {
                return caches.match('/offline/');
            } else if (event.request.url.includes('https://webmention.io/api/')) {
                return caches.match('/offline.json');
            }

        });
    })
}

What happens in the serveFromCache() function is:

Matches the request with the cache;
If the ignoreSearch parameter is true, it will set these parameters before matching;
If the checkExpiryListener parameter is true, and a cached file is found, the custom expiry header is checked;
If no cached file is found or the cached file has expired, fetch it and save it to the right cache;
If no cached file is found and the file can't be fetched, return the offline page that was cache when installing the service worker. If the request was for webmention.io, return the offline.json file.

The `updateCache()` function

/**
 * update cache
 * @param {Object} request the event request
 * @param {String} cacheName the cache to update
 * @return {Object} response object
 */
function updateCache(request, cacheName) {
    return caches.open(cacheName).then(function (cache) {
        return fetch(request).then(function (response) {
            
            var responseCopy = response.clone();
            var headers = new Headers(responseCopy.headers);
            headers.append('sw-fetched-on', new Date().getTime());

            var requestKey = request;

            // make sure the request with query params of style.css are not saved as a different asset
            if (request.url.includes('/css/style.css')) {
                requestKey = '/css/style.css';
            }

            return responseCopy.blob().then(function (body) {
                return cache.put(requestKey, new Response(body, {
                    status: responseCopy.status,
                    statusText: responseCopy.statusText,
                    headers: headers
                }));
            });

        });
    });
}

What happens in the updateCache() function is:

Open the right cache;
Fetch the file;
Add the timestamp as a custom header of the file;
Cache the file (make sure to cache the CSS file without the query parameters).

The `isCacheResponseStillValid()` function

/**
 * check of cacheResponse is still valid
 * if file isn't cached longer than 24 hours, it's still valid
 * @param {Object} cacheResponse the cacheResponse object
 * @return {Boolean} if true, cacheResponse is valid
 */
 function isCacheResponseStillValid(cacheResponse) {
	if (!cacheResponse) {
        return false;
    }
	
    var fetched = cacheResponse.headers.get('sw-fetched-on');
	
    // ms * seconds * minutes * hours
    if (fetched && (parseFloat(fetched) + (1000 * 60 * 60 * 24)) > new Date().getTime()) {
        return true;
    }

	return false;
};

What happens in the isCacheResponseStillValid() function is:

Check if a cache response was found;
Get the custom header with the timestamp;
Check if the timestamp is older than a day. If it's not, the cache is valid. If it is, the cache should be updated.

Some handy tricks

There are some handy tricks I've used in the service worker to reach the goals I've set.

Handy trick #1: Ignore query parameters in request

If you've read my note Cache busting in Eleventy you might remember that I'm using a query parameter added to my CSS file, like /css/style.css?v=1623355015, to make sure the browser cache won't serve an older version of the stylesheet. This however was causing a problem in combination with the service worker. If you look at the list of core assets I defined earlier, you can see that it contains /css/style.css. By default this means the service worker won't recognize the /css/style.css?v=1623355015 request as cached, because strictly speaking it's another request.

While matching the request to the cached assets it's possible to add extra parameters to ignore these query parameters. So to make sure that the request for /css/style.css?v=1623355015 will return the cached asset /css/style.css, I'm using these parameters as such: caches.match(event.request, {ignoreSearch:true}}).

Handy trick #2: Serve first, update second

To speed up the website I wanted to serve assets from the cache (if available). But I also wanted to make sure the cached assets are up to date. This was relatively easy to implement by using the code on serviceworke.rs. It uses respondWith() to immediately serve the request from cache, followed by waitUntil() to update the cache in the background. I only want to update the core assets though, so I've added a check for this.

Handy trick #3: Control the cache expiry

If a service worker caches a file, it's cached. There's no expiry header for these files. But in order to reach my goal of optimizing the requests to webmention.io I wanted to cache these requests for a limited period of time. My plan was to cache the webmention.io request for a day, so if a single user visits an article it will only make this request once a day.

I found this Go Make Things article which does exactly that. In short it intercepts the request and adds a header with a timestamp to it before caching it. When fetching a request from the cache it checks this header to see if it's still valid or not.

Bonus trick: Using service workers on your development environment

For service workers to work an HTTPS connection is required. There is an exception for http://localhost[:port] and http://127.x.y.z[:port] however, but if you're using custom domains for your development environments (like I am) you can't use service workers.

Luckily you can change some settings in Chrome and Firefox to enable service workers on HTTP connections. Stack Overflow to the rescue!

Loading the service worker

It took a bit of diving into the documentation, searching for references and (of course) some trial and error, but eventually I reached all of my goals. Only thing left is to make sure the website loads the service worker. This is pretty straight forward:

<script>
    if ('serviceWorker' in navigator) {
      navigator.serviceWorker.register('/sw.js');
    }
</script>

The if statement is to check if the browser is supporting service workers.

And that's it. The service worker is finished. The website will cache all the core assets when installing the service worker, it will serve from cache if possible, it will update the cache in background and it has a limited cache for certain requests. You can find the complete code on GitHub. If you have any questions or remarks, please hit me up on Twitter.

Automatically generate open graph images in Eleventy

2021-05-10T00:00:00Z

When sharing links on social media, it's nice to have an image instead of just the link. To achieve this you can implement the og: meta tags. You can check out the Open Graph protocol for more information about all the available tags. To define this image you can use the og:image meta tag. This can be a static image of the logo of your website for example, but for articles it's nicer to have the image contain the title and the date of the article.

Ofcourse you can create these manually, but that's a lot of work. It would be way easier to have them generated automatically whenever you add an article. So let's do this.

Getting started

While researching implementations of other people I came across the article 11ty: Generate Twitter cards automatically by Stefan Baumgartner which comes awfully close to what I'm trying to achieve. The only thing I want to do differently is that I want to solely rely on Eleventy for this, no other tools. So where he uses Gulp to ultimately generate the .jpeg files, I want to use Eleventy for this as well.

What I want to achieve is:

Create a SVG for every post;
Convert the SVG to a JPEG;
Add meta tags to website.

Create a SVG for every post

The advantage of SVG is that you can create an image by code. This makes it perfect to automatically create a base file for the Open Graph image. I have to create this for every single post. To do this we can use the collections functionality in Eleventy combined with the pagination parameter. Every post is stored in a collection in Eleventy and by setting the pagination parameter to 1 it will generate a new page for every post.

I created a new file to create the SVG's with the following front matter:

---
pagination:
  data: collections.notes
  size: 1
  alias: preview
permalink: "/img/social-preview-images/{{ preview.data.date | postDate }}-{{ preview.data.pageTitle | slug }}-preview.svg"
eleventyExcludeFromCollections: true
---

The alias parameter sets the variable name which contains all the information of the post. The permalink parameter sets the location to which the posts are saved (the postDate filter is a filter that formats the date in a yyyy-mm-dd format). And lastly the eleventyExcludeFromCollections set to true makes sure to not include these files in other collections.

Here's the full file I use to create the SVG's. I'll highlight some items after the code.

---
pagination:
  data: collections.notes
  size: 1
  alias: preview
permalink: "/img/social-preview-images/{{ preview.data.date | postDate }}-{{ preview.data.pageTitle | slug }}-preview.svg"
eleventyExcludeFromCollections: true
---
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg width="1200" height="628" viewBox="0 0 1200 628" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">

    {% set titleInLines = preview.data.pageTitle | splitlines %}
    {% set numberOfLines = titleInLines.length %}
    {% if numberOfLines == 1 %}
        {% set verticalStartingPoint = 340 %}
    {% elseif numberOfLines == 2 %}
        {% set verticalStartingPoint = 290 %}
    {% elseif numberOfLines == 3 %}
        {% set verticalStartingPoint = 250 %}
    {% elseif numberOfLines == 4 %}
        {% set verticalStartingPoint = 210 %}
    {% endif %}

    <rect width="100%" height="100%" fill="white" />

    <text text-anchor="start" font-family="'Giant Head OT', Helvetica, sans-serif" font-size="200">
        <tspan x="80" y="350">bn</tspan>
    </text>

    <line x1="300" y1="80" x2="300" y2="548" stroke="black" />

    <text font-family="Asap, Helvetica, sans-serif" font-size="30">
        <tspan x="350" y="{{verticalStartingPoint - 90}}">{{ preview.date | readablePostDate }}</tspan>
    </text>
    
    <text id="text" font-family="Asap, Helvetica, sans-serif" font-size="80" font-weight="bold">
    {% for line in titleInLines %}
        <tspan x="350" y="{{verticalStartingPoint + loop.index0 * 80}}">{{line}}</tspan>
    {% endfor %}
    </text>

</svg>

The splitlines filter

Because SVG doesn't support multiline texts we need to do this ourselves. This is a filter I copied from the article I mentioned before. It splits up the given text by words (the page title in this case) and creates an array of lines depending of the maximum size of characters per line (19 in my case).

module.exports = function(eleventyConfig) {
    
    eleventyConfig.addFilter('splitlines', function(input) {
        const parts = input.split(' ');
        const lines = parts.reduce(function(prev, current) {

        if (!prev.length) {
            return [current];
        }
        
        let lastOne = prev[prev.length - 1];

        if (lastOne.length + current.length > 19) {
            return [...prev, current];
        }

        prev[prev.length - 1] = lastOne + ' ' + current;

        return prev;
        }, []);

        return lines;
    });

};

Setting the right vertical position per line

I want the text to be centered vertically so I needed to calculate the vertical starting point. Because a title that uses 4 lines has a different starting point than a title that uses just 1 line. This comes down to a bit of trial and error. Just change it and see if it's what you want.

While looping through the lines I add to the defined starting point to make sure the following line isn't printed directly over the previous line, but it renders below the previous line.

Convert the SVG to a JPEG

So now that I have the SVG's generated for each post, I need to convert these to JPEG's (because Open Graph doesn't support SVG's in their image tag). This is where the Eleventy Image plugin comes in to play. This plugin can - among other things - convert images, for instance SVG images to JPEG images.

To convert the SVG's to JPEG's I've added the following code to my .eleventy.js file:

const fs = require("fs");
const Image = require("@11ty/eleventy-img");

module.exports = function(eleventyConfig) {
    
    eleventyConfig.on('afterBuild', () => {
        const socialPreviewImagesDir = "_site/img/social-preview-images/";
        fs.readdir(socialPreviewImagesDir, function (err, files) {
            if (files.length > 0) {
                files.forEach(function (filename) {
                    if (filename.endsWith(".svg")) {

                        let imageUrl = socialPreviewImagesDir + filename;
                        Image(imageUrl, {
                            formats: ["jpeg"],
                            outputDir: "./" + socialPreviewImagesDir,
                            filenameFormat: function (id, src, width, format, options) {

                                let outputFilename = filename.substring(0, (filename.length-4));
                            
                                return `${outputFilename}.${format}`;

                            }
                        });

                    }
                })
            }
        })
    });

};

I'm making use of the afterBuild event of Eleventy. This allows me to parse the generated SVG's and convert them to JPEG's. What happens in the code above is:

It defines the directory where the SVG images are stored;
It reads this directory and loop through the files in it using the file system module;
It only parses files with an .svg extension, because I'm saving the JPEG files in the same folder;
It uses the Eleventy Image plugin to convert the .svg to a .jpg file.

Using webfonts

You can use webfonts in the SVG's. At first I defined the webfonts in the <style> tag in the SVG. This works fine in the SVG, but when I converted it to a JPEG file, it didn't use the defined font. The Image plugin doesn't parse the fonts in the SVG and therefor uses a system font instead. The easiest solution to this is to install the fonts on your system. Now the fonts are parsed correctly when generating the JPEG file.

Add generated image to `<meta>` tags

Now that I have the generated image, I need to add this to the <meta> tags of the page. For now I've only generated these images for my notes, which are the only pages with tags. I've created a default fallback for other pages. This results in the following code:

<meta property="og:title" content="{% if page.url == "/" %}Bernard Nijenhuis • Front-end Developer{% else %}{{ pageTitle }}{% endif %}" />
<meta property="og:url" content="{{ page.url }}" />
{% if tags %}
<meta property="og:image" content="https://bnijenhuis.nl/img/social-preview-images/{{ page.date | postDate }}-{{ pageTitle | slug }}-preview.jpeg" />
<meta property="og:image:secure_url" content="https://bnijenhuis.nl/img/social-preview-images/{{ page.date | postDate }}-{{ pageTitle | slug }}-preview.jpeg" />
{% else %}
<meta property="og:image" content="https://bnijenhuis.nl/img/default-preview.jpeg" />
<meta property="og:image:secure_url" content="https://bnijenhuis.nl/img/default-preview.jpeg" />
{% endif %}

I'm setting the og:title to the page title, except for the homepage, because I want that to be different. The og:url is set to the current url. The og:image is set to the generated JPEG file if the page has tags, otherwise it will be the default image I created. Make sure to make this url absolute, or else it won't be parsed correctly.

Twitter specific `meta` tags

To optimize this for Twitter there are a couple of exta meta tags needed. The images that are generated are 1200 pixels wide and 628 pixel high (this is a 16:9 ratio). This is the recommended size for an "Image from a Tweet with shared link" according to Sprout Social.

The specific meta tags for Twitter are:

<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:site" content="@bnijenhuis" />
<meta name="twitter:creator" content="@bnijenhuis" />

The value 'summary_large_image' makes sure the image is displayed above the Twitter card, instead of as a small thumbnail on the left of the card.

Conclusion

I've now taken all the steps to automatically generate the Open Graph images in Eleventy, without using any external tools. You can find my specific implementation on GitHub. If you have any questions or remarks, please hit me up on Twitter.

Implementing clientside webmentions

2021-05-03T00:00:00Z

I came across webmentions a while ago and I wanted to try it out. If you don't know what a webmention is, Wikipedia describes it as follows:

Webmention enables authors to keep track of who is linking to, referring to, or commenting on their articles. By incorporating such comments from other sites, sites themselves provide federated commenting functionality.

For a static website as the one you're on right now, webmentions enable me to load likes, reposts and replies I get on for example Twitter in the page itself. Now there are several articles about implementing webmentions, but I hit a few bumps in the road while implementing it. I'll try to explain everything step by step in this note so you can avoid those bumps. I used the articles Using Webmentions in Eleventy by Max Böck and Clientside Webmentions by Shawn "swyx" Wang as references.

Enable webmentions for your website

If you want to include webmentions on your website you'll need a service that collects all the webmentions for you. Webmention.io is a service that does that for you for free. To register your website with Webmention.io, your homepage and social media profiles need to link to each other for verification. To do this you need to follow these steps:

Add rel-me links to your homepage for the various ways to reach you. You used to be able to verify via Twitter and Instagram, but for now only GitHub seems to be supported. Make sure the link to your GitHub profile has the rel-attribute set to the value me, e.g. <a href="https://github.com/bnijenhuis" rel="me">GitHub</a>;
Every social media profile you linked to must have a link back to your website in your profile. This is used for the verification process;
Finally, include <link rel="authorization_endpoint" href="https://indieauth.com/auth"> on your homepage.

If you have followed these steps you can sign in your website at Webmention.io. After signing in you will see the supported providers (the social media links you provided with the rel-me attribute) with buttons to verify them. Click on the button of the provider to finalize the verification process. The last thing you have to do to make sure your website can accept webmentions is to add the webmention and pingback metatags to your website. You can find them on the settings page of Webmention.io after you signed in. These are the tags I use on my website, yours will be similar:

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

Link your social media

Now your website has been registered to collect webmentions, but what you really want is to have them automatically collected from your social media. Brid.gy is a service that does that for you, also for free. If you want Bridgy to check your Twitter account for webmentions, you just need to click the Twitter button and authorize Bridgy. It will directly start to analyze your tweets, but you can submit specific tweets as well.

Load the webmentions on your website

You've now enabled your website for webmentions and linked your social media so the webmentions are automatically collected. Now all you need to do is show them on your website. Webmention.io has an API you can use for this. For my website I'm using two API endpoints, the count endpoint and the mentions endpoint.

The count endpoint gives a summary of the number of all the webmentions as a total and split up by type of webmentions. This endpoint requires a target parameter, which is the full url of the page you want the webmentions of. For instance:

<script>
    const postUrl = "https://bnijenhuis.nl/notes/2021-04-30-implementing-clientside-webmentions/";

    fetch("https://webmention.io/api/count?target=" + postUrl)
    .then(response => response.json())
    .then(responseJson => 
        console.log(responseJson) // do whatever you like with it
    );
</script>

This will return something like this:

{
    "count":17,
    "type":{
        "like":14,
        "mention":1,
        "reply":1,
        "repost":1
    }
}

The mentions endpoint gives you all the details of the webmentions. This endpoint requires the same target parameter as the previous endpoint and can be extended with some parameters for sorting the webmentions. For instance:

<script>
    const postUrl = "https://bnijenhuis.nl/notes/2021-04-30-implementing-clientside-webmentions/";

    fetch("https://webmention.io/api/mentions.jf2?target=" + postUrl + "&sort-by=published&sort-dir=up")
    .then(response => response.json())
    .then(responseJson => 
        console.log(responseJson) // do whatever you like with it
    );
</script>

This will return something like this (this is an excerpt from some webmentions on my previous post):

{
    "type": "feed",
    "name": "Webmentions",
    "children": [{
        "type": "entry",
        "author": {
            "type": "card",
            "name": "Behdad Esfahbod",
            "photo": "https://webmention.io/avatar/pbs.twimg.com/65203a0b3d791846c880319f60dcdb423fc4246ea31f51b82c4ddc6c7819329f.jpg",
            "url": "https://twitter.com/behdadesfahbod"
        },
        "url": "https://twitter.com/bnijenhuis/status/1382593304701833216#favorited-by-15402347",
        "published": null,
        "wm-received": "2021-04-26T21:06:28Z",
        "wm-id": 1133909,
        "wm-source": "https://brid.gy/like/twitter/bnijenhuis/1382593304701833216/15402347",
        "wm-target": "https://bnijenhuis.nl/notes/2021-04-13-how-to-add-self-hosted-variable-fonts-to-your-website/",
        "like-of": "https://bnijenhuis.nl/notes/2021-04-13-how-to-add-self-hosted-variable-fonts-to-your-website/",
        "wm-property": "like-of",
        "wm-private": false
    }, {
        "type": "entry",
        "author": {
            "type": "card",
            "name": "Bram.us",
            "photo": "https://webmention.io/avatar/pbs.twimg.com/2d58128eca8ca19f950d63446a08ff738b7629792495ae912ca559c3b5aa9503.jpg",
            "url": "https://twitter.com/bramusblog"
        },
        "url": "https://twitter.com/bramusblog/status/1386782975006740480",
        "published": "2021-04-26T20:43:21+00:00",
        "wm-received": "2021-04-26T21:08:16Z",
        "wm-id": 1133911,
        "wm-source": "https://brid.gy/comment/twitter/bnijenhuis/1386782265552801801/1386782975006740480",
        "wm-target": "https://bnijenhuis.nl/notes/2021-04-13-how-to-add-self-hosted-variable-fonts-to-your-website/",
        "content": {
            "html": "Cool! 👌\n<a class=\"u-mention\" href=\"https://bnijenhuis.nl/\"></a>\n<a class=\"u-mention\" href=\"https://twitter.com/bnijenhuis\"></a>",
            "text": "Cool! 👌"
        },
        "in-reply-to": "https://bnijenhuis.nl/notes/2021-04-13-how-to-add-self-hosted-variable-fonts-to-your-website/",
        "wm-property": "in-reply-to",
        "wm-private": false
    }]
}

And that's it. For a specific (Eleventy) implementation you can find my implementation on GitHub. If you have any questions or remarks, please hit me up on Twitter.

Paging

By default the mentions endpoint returns a maximum of 20 entries. This means that of you have more than 20 webmentions, not all of them will show. There's a parameter to override the default though. It's the per-page parameter. You can set this to a value that you think will always include all webmentions, but since I already made the call to get the total count of webmentions I can get that specific count of webmentions. With some minor tweaks to the code I've ended up with this:

<script>
    const postUrl = "https://bnijenhuis.nl/notes/2021-04-30-implementing-clientside-webmentions/";

    fetch("https://webmention.io/api/count?target=" + postUrl)
    .then(response => response.json())
    .then(function (responseJson) {
        
        fetch("https://webmention.io/api/mentions.jf2?target=" + postUrl + "&sort-by=published&sort-dir=up&per-page=" + responseJson.count)
        .then(response => response.json())
        .then(responseJson => 
            console.log(responseJson) // do whatever you like with it
        );

    });
</script>

Cache busting in Eleventy

2021-04-23T00:00:00Z

Because I'm still following my Unhurried Development principle I'm taking small steps and making small changes. That's how I came across an issue with cached assets^[1]. A cached CSS file in my case, to be specific. And although it's easy to force reload on desktop browsers, this is a lot harder on mobile devices. Besides, visitors don't know they are using a CSS file that is served from cache, so they only see the changes when the cache expires.

To make sure the file isn't served from the cache, the url of the file needs to change. But I don't want to change the file url manually every time I've changed the file. But you know what automatically changes when changing a file? That's right! The datetime modified of the file itself!

This probably has been done before in Eleventy, so while searching for a solution I came across a cache busting article for Eleventy by Rob Hudson. He basically had the same idea as I had and created a filter for Eleventy. But instead of getting the datetime modified of the file, he used the current datetime. This was a good starting point for me, as I'm kinda new to creating filters in Eleventy. So now I had the following filter:

eleventyConfig.addFilter("bust", (url) => {
    const [urlPart, paramPart] = url.split("?");
    const params = new URLSearchParams(paramPart || "");
    params.set("v", DateTime.local().toFormat("X"));
    return `${urlPart}?${params}`;
});

I could have a unique url for my CSS file by using this filter like so:

{{ '/css/style.css' | url | bust }}

which would render into something like this:

<link rel="stylesheet" href="/css/style.css?v=1604094309" />

The next step was to find a way to get the datetime modified of the file. That's where the file system module comes into play. By using this module I can interact with the file system. To get the datetime modified of a file I needed the fs.statSync function which accepts a path parameter of the file that you want the statistics of. The path to use should be relative though and the path given is absolute, so I needed to fix this as well. Furthermore I placed it in a try catch block, just in case something goes wrong and it ruins the whole build.

With all these modifications I ended up with the following filter:

const fs = require("fs");

module.exports = function(eleventyConfig) {
    eleventyConfig.addFilter("bust", (url) => {
        const [urlPart, paramPart] = url.split("?");
        const params = new URLSearchParams(paramPart || "");
        const relativeUrl = (urlPart.charAt(0) == "/") ? urlPart.substring(1): urlPart;

        try {

            const fileStats = fs.statSync(relativeUrl);
            const dateTimeModified = new DateTime(fileStats.mtime).toFormat("X");

            params.set("v", dateTimeModified);

        } catch (error) { }
            
        return `${urlPart}?${params}`;
    });
}

When using this filter it will:

Split up the url on the ? character, just in case some url parameters were already given;
Create a variable with the given url parameters;
Make sure the url is relative;
Find the file and get the timestamp of the datetime modified;
Added the timestamp to the url parameters;
Add the new url parameters to the file url.

Now my CSS file url will only update if the CSS file itself has been changed.

^[1] I should point out that if you're on the JAMstack, for instance Netlify, this probably won't be a problem, because they often handle it for you.

How to add self-hosted variable fonts to your website

2021-04-13T00:00:00Z

To give my website a bit more personality I wanted to use a webfont instead of a system font. And because variable fonts are gaining traction I thought I would give it a shot.

If you're not familiar with variable fonts, I would suggest you read the Introduction to variable fonts on the web. In short, variable fonts can be described by the following quote from the mentioned article:

Many font families offer a much wider range of styles, from Thin to Black weights, narrow and wide widths, a variety of stylistic details, and even size-specific designs (optimized for large or small text sizes.) Since you'd have to load a new font file for every style (or combinations of styles), many web developers choose not to use these capabilities, reducing the reading experience of their users.

...

Variable fonts address these challenges, by packing styles into a single file.

There are quite a lot of variable fonts available on Google Fonts, so there's a lot to choose from these days. When you've made your choice you can download the font family from Google Fonts. By doing this you get the TTF file(s) of the variable font. Normally I would run them through Font Squirrel, Transfonter or some other online tool to create a WOFF2 file that I can use as a webfont. But these tools aren't capable of handling variable fonts.

So what now?

I decided to drop a message to Roel Nieskens. He's the creator of Wakamai Fondue, is a co-author of the aforementioned article, does a lot of stuff that is font related, and he's Dutch...so yeah. He suggested I use a woff2 tool by Google to convert the TTF file to WOFF2. I also found an article by Henry Desroches describing step by step how to use that same tool. This worked just as described so I really recommend this tool (and article for that matter).

Filesize

You'd think the filesize of a variable font would be considerably larger because it contains all the styles in one file. And if I compare the size of the variable font file to the size of one of the static font files, there certainly is a difference. For instance, I'm using the Asap font family and the filesize of the variable font is 243kb while the filesize of the regular static font file is 148kb. But so is the medium file, the semi bold file, the bold file, etcetera. So all in all the variable font is already relatively small.

When I converted the variable font to a WOFF2 file, the filesize went down to only 56kb. That's pretty small considering it contains all the weights of the font.

How to implement it

Now that we have the converted variable font, we only need to add it to the stylesheet. It's mostly the same as you would implement a static font. Here is the font-face declaration I use:

@font-face {
    font-family: Asap;
    src: url('/fonts/Asap-VariableFont_wght.woff2') format('woff2 supports variations'),
         url('/fonts/Asap-VariableFont_wght.woff2') format('woff2-variations');
    font-weight: 400 700;
    font-display: swap;
    font-style: normal;
}

If you look at the src property you can see I use two types of format declarations. The first one is the format that will be the default in the future for all browsers and the second one is the soon to be deprecated format.

You might notice the font-weight property is defined by two values. This means that this particular font supports weights between 400 and 700. Some variable fonts also have a font-stretch property and you can add this as well. To find out what values you should use with your variable fonts you can upload the font to Wakamai Fondue to get all the specifications of your font.

Fallbacks

Variable fonts are pretty well supported. The nice thing about variable fonts is that it will always provide one style as a built in fallback so it works on non variable fonts supporting systems as a static font. Mostly it will be the regular style, but it can differ per font.

If the regular style is the built in fallback and the browser needs to render a bold text, it might create a faux bold (this depends on the browser). It's not always what you want, but for a fallback it might be enough. If you don't want the browser to create the faux bold you will need to include the static bold font file. Also, when the built in fallback isn't the style you want (because for some obscure reason the fallback style is italic or something), you have to load the static font separately as well.

For the Asap font the built in fallback style is the regular style. So for non supporting browsers declaring only the variable font will result in text rendered in the regular style. If you want the other styles rendered as they're supposed to you'll need the define all the styles first. Then follow up with a @supports declaration for the variable font, like below, to load the variable font for supporting browsers:

@font-face {
    font-family: Asap;
    src: url('/fonts/Asap-Regular.woff2') format('woff2');
    font-weight: normal;
    font-display: swap;
    font-style: normal;
}

@font-face {
    font-family: Asap;
    src: url('/fonts/Asap-Bold.woff2') format('woff2');
    font-weight: bold;
    font-display: swap;
    font-style: normal;
}

@supports (font-variation-settings: normal) {
    @font-face {
        font-family: Asap;
        src: url('/fonts/Asap-VariableFont_wght.woff2') format('woff2 supports variations'),
            url('/fonts/Asap-VariableFont_wght.woff2') format('woff2-variations');
        font-weight: 400 700;
        font-display: swap;
        font-style: normal;
    }
}

So that's it. That's all there is to it to implement self-hosted variable fonts to your website.

Creating a feed in Eleventy

2021-04-07T00:00:00Z

With the rise of all the different social media platforms several years ago, RSS was deemed unnecesary. Even Google discontinued Google Reader in 2013. But with the weird algorithms used in social media, lots of people (well, lots of developers at least) still rely on feeds to have a chronological feed of articles they're interested in.

Eleventy provides a RSS plugin to generate a feed for your Eleventy project. What the RSS plugin actually does is create an Atom feed instead of a RSS feed, but they are basically the same. A quick search led me to an article by Daniel Miessler about the differences between RSS and Atom and why Atom is actually the preferred method. He makes some solid points, and because it agreed with the simplest way for me to add a feed to my website, I chose to listen to him :).

For a minute I considered to create a feed myself without using a plugin, but when I looked at the code of the plugin it was pretty clean already. It already handles things like making sure that urls are absolute and getting the last updated date. It made no sense to do this myself so I followed the steps described on the RSS plugin page to implement a feed on my website.

One thing I did change though, is the order in which the entries are listed in the feed. In the example given on the plugin page the entries will be sorted from old to new, but I think it makes more sense to have the newest entry first. To do this, I only needed to add |reverse to the for declaration like this:

{%- for note in collections.notes|reverse %}

So now you're able to subscribe to my notes using your favorite feed reader!

Adding a favicon in Eleventy

2021-03-25T00:00:00Z

I recently stumbled upon an article posted on CSS-Tricks about How to Favicon in 2021. Usually I would just use whatever a Favicon Generator would output for me, but it always felt like it returned...well...a lot!

That's great though, because you can serve a favicon on every browser and in every occasion. But, as the article the CSS-Tricks article refers to states, not all of them are really needed anymore. For more information on what files are needed and how to create them just read the other two articles. There's no need to explain them here as well.

After creating the correct files, I needed to add them to my Eleventy project. I wanted to have them placed in my root directory when generated, but I want them in a seperate folder in my project. That's where Passthrough File Copy comes into play. You can define files and/or folders to passthrough to your generated content.

I've added the following to my .eleventy.js file:

// Copy `img/favicon/` to `_site/`
eleventyConfig.addPassthroughCopy({ "img/favicon": "/" });

All it does is get the files from the img/favicon folder of my project (where I placed the created favicon files) and pass them through to the root of the generated content.

This is a basic implementation of this functionality. If you want to learn more implementations and variations of Passthrough File Copy you can read the docs as linked earlier.

Collection archive in Eleventy

2021-03-17T00:00:00Z

When creating collections, like I am with these notes, it's expected to have an index file of all the posts. All my notes are under the /notes/ url path, but by default the /notes/ url path itself isn't available. ~~And creating a file in the notes folder in the Eleventy project won't fix this, because this will create a new note by itself.~~ Nicolas Hoizey pointed out on Twitter that it is possible, more on that at the end of this note.

Luckily it's pretty easy to create such an index file using the permalink option in the frontmatter. This option enables you to control the location of the created file. In my case I wanted to create an index file for all my notes, so I created the file notes-archive.njk in the root directory of my project with the following frontmatter:

---
layout: layout.liquid
permalink: /notes/
---

As you can see the permalink option has the /notes/ value, which means the file will be created at that url path, instead of the default /notes-archive/ url path. That's all there is to it to create a basic collection archive or tag page. More information can be found in the Eleventy documentation.

Update March 18, 2021

As I mentioned earlier, it has been brought to my attention that it is possible to create an index file in the /notes/ folder. To make this work you have to use the eleventyExcludeFromCollections option in the frontmatter and set this to true, like this:

---
layout: layout.liquid
eleventyExcludeFromCollections: true
---

The option is pretty self explanatory. If you add this to the frontmatter and set it to true, it won't be added to the collection. I think this is a better solution, because the structuring of the files in your project is much more logical. So both methods work, but I would suggest using this last method.

Dates in Eleventy

2021-03-09T00:00:00Z

When writing notes it's important to add a date to them. Even if it's just for your own use, it can be really helpful for future you to directly see how recent and relevant the note is. Because in the ever changing world of front-end development just a year can make a real difference.

Seeing how many starter blogs are available for Eleventy, I thought the date support would be baked in. And to be fair, it kinda is, but when you want to control the format you need to do a little extra. And when I say a little, it really is a little. A great website for Eleventy related resources is 11ty.rocks, and they have an article about dates as well.

I wanted to use a different formatting than described in that article, but a quick search for Luxon date formatting led to the documentation. So I created the .eleventy.js file and created the following filters:

eleventyConfig.addFilter("readablePostDate", (dateObj) => {
    return DateTime.fromJSDate(dateObj, {
        zone: "Europe/Amsterdam",
    }).setLocale('en').toLocaleString(DateTime.DATE_FULL);
});

eleventyConfig.addFilter("postDate", (dateObj) => {
    return DateTime.fromJSDate(dateObj, {
        zone: "Europe/Amsterdam",
    }).setLocale('en').toISODate();
});

The readablePostDate filter creates a date like March 9, 2021, and the postDate filter creates a date like 2021-03-09, which is used in the time element on the homepage and the note itself.

Unhurried Development

2021-03-01T00:00:00Z

I recently changed hosting and instead of moving my old website, I thought it was the perfect time to build the new website I had in my mind for a while now. The only problem was, I hadn't even started on it yet. And before I would have it at a stage where I feel comfortable enough to share it, it could be weeks, months...years even!

I didn't want to wait that long, so I decided to just start. Just develop the website in small steps, without any pressure. Because let's face it, there's enough stress in the world at the moment. No need to add some more to myself.

I started with the thing I do best and have the most experience in: procrastinating. First I wanted to have a name for this kind of development. The first thing that came in my mind was "lazy", but it felt a bit too negative, as did "slow". After some searching for synonyms of these terms, I came across "unhurried". And it feels like the perfect term to use. No hurry, no pressure, no negative connotation. Just develop what I want, when I want.

So with that sorted out, there wasn't anything else I could think of to stop me of beginning the project (trust me, I really tried to find something). Time to start. My last website was just handcoded HTML, but I wanted to try a SSG. I decided to use Eleventy to create this website. It's a really fast SSG, with lots of documentation and an active community.

Although there are a lot of starter projects, I will not be using one to try and keep the code as clean as possible and only include what I need. I started by following this blog tutorial by Zach Leatherman (the creator of 11ty). I added a few CSS rules to make it readable, but that's it for now. To be honest, it took me longer to write this first post than setting up the basics.

The plan is to make notes on every step I make, so I can get a little better at writing as well. But as I said earlier, there is no timeframe. Just a bunch of ideas in my head that I want to work out.

So that's it, the start of my Unhurried Development project. I'll keep you posted. Probably.