Martin Gunnarsson

Advent of Code 2025:3, Rockstar edition

Martin Gunnarsson — Mon, 08 Dec 2025 20:48:42 +0000

Having solved the first and second Advent of Code puzzles in Rockstar, it was only a matter of time before I finished the third one. Hopefully the assignments will be too difficult soon ...

Let the letter be gone
Put it into the fire
Listen to the wind
Until it is gone
Scream the wind
Shatter it into shards
The heart is like loneliness
Put shards with the heart into the abyss
Cast nothing into darkness
Let the light be it
My dreams are so cumbersome
Put the heart into the beginning
The soul is levitating
Build it up
While my dreams are lower than the abyss without the soul
Let hope be shards at my dreams
If it's greater than darkness
Put hope into darkness
Let the beginning be my dreams
If hope is crackling break on to the other side, yeah!
Build my dreams up, baby
Let my dreams be the beginning
Build them up
While my dreams is less than the abyss
Put shards at them into hope
If it's greater than the light, put it into the light, yeah
Build my dreams up, baby
Put darkness with the light into the smoke
Cast it with like a superpower
The fire is with the smoke
Listen to the wind
Yeah
Shout the fire

Advent of Code 2025:2, Rockstar edition

Martin Gunnarsson — Sun, 07 Dec 2025 17:39:42 +0000

Background

The other day I posted my first attempt at coding in Rockstar. After that I couldn't help myself, and continued with the second Advent of Code puzzle.

The code

Just like the first time, I wrote a little JavaScript implementation first, to make sure my logic was sound, then I implemented it in Rockstar. This time I hit the ground running, and except for a few frustratingly vague error messages (Unexpected 'Let' at line 1 col 1: Failed to parse 'program', basically saying that this program here as a whole couldn't be parsed) I got it working fairly easily. This time I decided to make it sound a bit like a Christmas rock song, but it also ended up sounding a bit like a cookie recipe.

Everybody wants cookies
Cut silence with cookies into joy
His dreams are so overloaded
Let the holiday be joy with them
Let angels be silent
Put them into the night
Fire is like you
Let the spirit be like wow!
It is without fire
While the spirit is weaker than the holiday
Let praise be joy at the spirit
When the spirit is smaller than the holiday between like us
Angels are with praise
Otherwise, put the night with praise into the night, baby
Build the spirit up! Yeah
Let wonderful be angels are really the night
Let the message be it! Send it!

Listen to the singing
Let the dream be gone

The streets are silent
Rock them with like snow plow!
Let us be the streets

Put the singing into baking
The cookies are empty
Rock them with like corn flour!
Let the dough be baking

Cut the dough into pieces with us
Put the cookies into us

For the piece in pieces
Cut it into halves with us
Roll halves into the night; cast them with like a gingersnap
Roll halves into the oven; cast them with like a nutcracker
Let peace be the night
While peace is as low as the oven
When everybody taking peace is right
The dream is with peace, baby
Build peace up
Oh yeah
Shout the dream

Surely this is it now. I can't possibly be bothered writing another one of these, right?

Advent of Code, Rockstar edition

Martin Gunnarsson — Sat, 06 Dec 2025 14:39:42 +0000

Background

At Øredev I met my pal Fredrik, who told me about this presentation he had just been to. It was about a fun programming language called Rockstar, which lets you write 80's rock ballad lyrics that compile. Fun! One faithful evening a few weeks later, after the rest of the family had gone to bed, I decided to have a couple of beers and give it a try.

The code

Since we're approaching Christmas, it only felt appropriate to use the first Advent of Code puzzle as my first assignment. I signed in, read the instructions, and immediately decided to cheat and solve the problem in a more familiar language first. I wrote a quick JavaScript solution, verified the output, and moved on to Rockstar. Conveniently there's an online editor and interpreter right on the Rockstar website, so I was able to get started without downloading a single thing.

Rockstar was a little awkward to get used to, I basically jumped back and forth between the documentation and the online editor, slowly building up the same solution I had just written in JavaScript. Some of the examples in the documentation made no sense at all, as there are several quirky language features made specifically to enable coding in somewhat natural language. Other challenges included things like having to implement a crude modulo function of my own, since very few rock songs are about modulo operations.

I wrote the implementation in a clear style first, with clear variable names etc, and then had a bit of fun trying to dress it up as more of a rock song. I'm not really an expert in either esoteric programming languages, coding puzzles, or rock lyrics, so it's probably neither the best solution nor the best rock song, but at least it works!

So, without further ado, here's my solution to the first puzzle of Advent of Code 2025, written in Rockstar:

Magic is found everywhere
Space is like a rocketship, rocketship
The truth is empty
The west is empty
Rock them with like glitter horses!

The reaper takes the lover and the scythe
Let judgement be the lover
When judgement is weaker than nothing
Let it be nothing without it
Let the jester be right
Yeah
While judgement is as strong as the scythe, judgement is without the scythe, baby
If the jester is right let judgement be nothing without judgement
Give judgement back!

Listen to the word!
Until the word is gone
Roll the word into heading
Cast the word with like a loneliness
The force is bittersweet
When heading is the west, the others are like us
Put the force without them into the force, baby
Let progress be magic with the force of the word
Put progress into magic
The stars are like electricity
When magic is higher than space without the stars or magic is weaker than nothing,
let magic be the reaper taking magic & space, yeah!
When magic is empty, build the truth up, baby
Listen to the word
Yeah

Say the truth!

I had fun writing this, and I'm weirdly tempted to do it again, but I'm not making any promises. Maybe if I find myself with another evening on my own and a couple of cold beers at hand ...

Am I a bicycle commuter now?

Martin Gunnarsson — Mon, 18 Mar 2024 11:20:42 +0000

Two months ago I started collecting my thoughts on commuting by bike, mostly to convince myself to giving it a shot. Being in the middle of the winter, the weather was pretty rough for a period of time after that, but about a month later I rode to work for the first time. The weather was still a bit questionable on that day, with a very strong crosswind, but I went anyway and was thrilled to have taken the first pedal stroke.

This was 3-4 weeks ago, and including that first time I've now commuted by bike ten times. I've been working from home at least two days during this period as well, so I've actually commuted almost 60% by bike. That's a good start! One of the reasons this has worked out so well is that the weather has been surprisingly decent for this time of the year, with very little rain. I still haven't invested in rain clothes, so my choice of transportation is pretty weather-dependent.

Mornings like this, however, riding to work is a real pleasure.

Practicalities

I ride my simple but robust Skeppshult bicycle. Since it lacks racks or other luggage space I pack everything I need in a pretty tight Haglöfs Corker backpack. It has a laptop compartment along the back with just enough room for my 14" MacBook Pro in a neoprene sleeve. I also bring my notepad, lunchbox, a spare t-shirt, and a flexible steel lock for the bike. After a couple of rides I noticed my saddle had started coming loose, and added a small set of Allen keys to the backpack as well.

During this period we've had typical early spring weather, with temperatures between -2 and 8°C or so. I ride in my regular, casual office clothes, usually a pair of chinos and a t-shirt with a hoodie or a button-down shirt over, and then a fleece jacket as an outer layer.

I usually have a tailwind going to the office. Since it's also pretty cool in the morning, I rarely get sweaty from that ride. I've changed into my spare t-shirt once, but I wouldn't say it was strictly necessary, I just really want to avoid smelling offensive in the office. The ride home is a different story. It's warmer that time of the day, there's almost always a headwind, and the last kilometer (after battling that headwind over the open fields) is up a pretty tall hill. I've arrived at home very sweaty a number of times, but of course that isn't much of a problem. I think I'll have to find a thinner jacket soon though, since I tend to get very sweaty even without the middle layer of clothing.

Adjustments

The only thing I've been tweaking is my saddle position. I was a bit uncomfortable the first few rides, which is natural I guess, but also got a bit of numbness in the nether regions. After watching a few bike fitting videos and learning that most people (especially men) have their saddles too high, I tried lowering mine a bit. I think I got a bit of a smoother stroke as a result, and the numbness problem all but went away. I might try tweaking the position a bit more, but I think it's pretty good where it's at now.

Setbacks

After a couple of weeks I went to work by bike two days in a row for the first time, and after that an old annoying knee pain of mine re-surfaced. It's probably something like runner's knee or jumper's knee. I did see a physiotherapist about it regularly a few years ago, which had a positive effect, so I was pretty bummed-out about having it back. I really want to keep riding to work, and I've also signed up for a pretty cool half-marathon next summer, and have been thinking of my biking as a low-impact way of increasing my fitness and strenthening my legs before starting running again.

I decided to try riding to work again a couple of days later, and to my relief didn't feel any pain, so I've kept going. There's no way to tell whether the pain was caused by riding the bike or not. Perhaps I jumped around too much playing with the kids or something, I can't really remember. It's come and gone a bit since then, but it's been very mild and seemingly not gotten worse by biking.

Success

I feel really good on the days when I commute by bike. It's a great way of starting the day, and I get a lot of energy from it. From a physical perspective, the commute of course consumes energy rather than producing it, usually between 6-700 kcal for the rountrip according to my Apple watch, and I've noticed I feel more hungry now. I've also lost almost 2 kg without any other changes or efforts, so that's a nice side effect!

Conclusion

If I could find a good set of rain clothes I could see myself going all-in on bike commuting after getting used to it properly. I just hope I don't get held back by any annoying injuries. Riding every day I would really start to see financial benefits from it, on top of all the other positives, as I wouldn't have to pay for the monthly parking permit that I have now. In fact, I think I'm almost at the point where it would have been cheaper to pay by the hour for the days when I do drive rather than getting the monthly permit. Without rain clothes, however, not getting one is a bit of a gamble.

I record all my rides on Strava, and I'm always happy to find more inspiring people on there, so feel free to give me a follow. Happy riding!

Eleventy excerpts

Martin Gunnarsson — Fri, 15 Mar 2024 22:29:42 +0000

Background

Wherever I list posts on this site, e.g. on the Home page and Archive page, I want to display a reasonably long excerpt from the linked post, to give visitors an idea of its content. There seems to be an almost comical variation in what people want from excerpts - how long they should be, whether they should be marked manually or picked out automatically, or entered separately from the content altogether, whether images should be included or not etc. etc. Fun!

Of course I also have my own idea of how everything should work:

The excerpt should be an automatically selected portion of the beginning of the post.
Only body text should be included, no images, headlines etc.
All formatting should be removed.

I think that's it. Pretty modest requirements if you ask me.

The Eleventy solution

This site is built using Eleventy, and thanks to its use of the gray-matter npm package, Eleventy has a way of extracting excerpts from posts automatically. It requires manually setting the excerpt cutoff-point in the text, but you can freely choose what separator to use:

module.exports = function (eleventyConfig) {
    eleventyConfig.setFrontMatterParsingOptions({
        excerpt: true,
        excerpt_separator: "<!-- cut -->",
    });

    // Further configuration
};

With this snippet in place in your .eleventy.js, the item.data.page object will include a property called excerpt when iterating over collections:

{% for post in collections.post %}
<article>
    ...
    <p>{{ post.data.page.excerpt }}</p>
    ...
</article>
{% endfor %}

This solution works well, but I don't want to mark my excerpts manually. I feel pretty strongly that the content of the site should be kept as free as possible from technical implementation details. This feels like a good principle, and will also make the content as portable as possible.

Another limitation of this solution is that the excerpt generated will be extracted from the raw content, rather than the rendered page. I use Markdown for my posts, so the excerpts I get using the built-in functionality will be snippets of the unprocessed Markdown source. Stripping Markdown formatting from text is a lot trickier than e.g. stripping HTML, as there is no common formatting of control characters etc. I'm sure there are clever regular expressions out there that solves this, but I feel more confident stripping out HTML. Another common approach is to manually run the excerpt through the markdown-it processor used by Eleventy, but I always thought that felt a bit clunky and unnecessary. The page will be processed by markdown-it as part of the site rendering anyway, why do it again just to generate an excerpt?

My solution

I settled on building a custom solution in the form of an Eleventy filter, that extracts the excerpt from the rendered page rather than from the source. To keep my .eleventy.js as short as possible, I put the code in a separate class:

class ExcerptGenerator {
    getExcerpt(content, length) {
        let excerptParagraphs = [];
        let currentLength = 0;
        const paragraphs = content.match(/<p>.*?<\/p>/gs) || [];

        for (let paragraph of paragraphs) {
            // Strip HTML from the paragraph
            const text = paragraph.replace(/(<([^>]+)>)/gi, "");

            if (currentlength > 0 && currentLength + text.length > length) {
                break;
            }

            excerptParagraphs.push(text);
            currentLength += text.length;
        }

        return excerptParagraphs.join(" ");
    }
}

The code finds all paragraph tags in the content, and then starts picking them out one by one, until adding another one would break the specified length limit. As part of this process, any HTML within the added paragraphs is stripped. A bit of a brutal approach perhaps, but it gets the job done. It feels like there's an elegant map reduce-like solution to this problem, but I'm not so sure that elegant solution would be any easier to read or maintain. I could also have used something like Cheerio to first parse the HTML and then pick out the paragraphs that way, but that would most likely have been slower and probably not much of an improvement readability-wise either. I'll stick to the brutalist approach for now.

Usage

The filter is then hooked up in .eleventy.js:

const ExcerptGenerator = require("./_scripts/excerptgenerator");

module.exports = function (eleventyConfig) {
    eleventyConfig.addFilter("excerpt", function (content) {
        return new ExcerptGenerator().getExcerpt(content, 500);
    });

    // Further configuration ...

    return eleventyConfig;
};

The string passed into the addFilter function is the name that the filter will be accessed through, in this case excerpt. This filter name is now ready to be used from any template:

{% for post in collections.post %}
<article>
    ...
    <p>{{ post.templateContent | excerpt }}</p>
    ...
</article>
{% endfor %}

This code takes the template content, i.e. the rendered content, from each post and sends it through the excerpt filter, resulting in a reasonably sized excerpt void of any styling and formatting.

Drawbacks

The above solution has worked well for all posts I've written so far, but in theory it could generate somewhat incoherent excerpts in certain cases. Consider a post with a very short first paragraph, followed by an image or a code block, and then a second paragraph discussing that middle content. The excerpt for this post would just consist of a single string combining the first and the second paragraph, completely omitting the middle content, which could make the text a bit difficult to understand. I'll deal with that if and when it happens. Just like with the automatic image scaling I wrote about recently, my goal here isn't perfection, but to have a decent end-result without any manual work. The lazier I can be when publishing new content, the more likely I am to actually do it.

Conclusion

I see a lot of people implementing custom excerpt functionality in Eleventy, which is a testament to its flexibility. On the other hand, it also says something about the current excerpt support. A couple of the customizations I've implemented as part of this site in the past have been workarounds for little rough edges like this in Eleventy, and they have all since been made obsolete by improvements either in Eleventy itself or in official plugins. I have a feeling excerpts could be up for a revamp as well at some point in the future. Until then, I'm happy with my own little flavor of excerpts.

If you want to read more about the ways I'm using Eleventy on this site, I've collected all my posts on a separate Eleventy page. Happy blogging!

Automatic image pre-processing in Eleventy, Part 2

Martin Gunnarsson — Wed, 13 Mar 2024 05:41:42 +0000

Background

One of the Eleventy customizations I've set up for this site is automatic generation of responsive <picture> tags from images in Markdown posts. I was going to build it myself using the Eleventy Image plugin, but then randomly stumbled upon a plugin for the markdown-it Markdown processor used by Eleventy that did exactly that. It's called markdown-it-eleventy-img and provides the glue needed between the Eleventy Image plugin and the Markdown parsing performed by markdown-it. I wrote a post about this setup back in the day, but that is now obsolete. Starting with version 4.0.0, the Eleventy Image plugin itself performs all the steps needed itself.

Motivation

The main reason I want this functionality on my site is lazyness. Or, rather, I want to be lazy without paying the price! I want to be able to just dump a large JPEG or PNG image into the directory of one of my posts, include it as a regular Markdown image, and have it offered to the browser both in multiple sizes and various modern image formats.

Configuration

To get this functionality set up using Eleventy Image, you first need to install the plugin using npm:

npm install @11ty/eleventy-img

Next up, add it to your .eleventy.js and start adding some configuration:

const { eleventyImagePlugin } = require("@11ty/eleventy-img");

module.exports = function (eleventyConfig) {
    eleventyConfig.addPlugin(eleventyImagePlugin, {
        // The image formats to generate, in order of preference
        formats: ["avif", "webp", "auto"],

        // The images sizes to generate
        widths: [368, 736, 900],

        defaultAttributes: {
            sizes: "auto",
        },
    });

    // Further configuration ...
};

Assumptions

The first time I set this functionality up, I realized my assumption about the browser's image format selection was incorrect. I thought that you could just offer a number of different formats, and the it would pick the best one automatically. In hindsight that feels a bit naïve, what is even the best format? Instead, the browser picks the first format it has support for, so the order of the formats matter.

Once my post on the subject was published I got some very helpful feedback, that made me realize my assumption about the size selection was also incorrect. Again, I thought you could offer a number of different image sizes, and the browser would pick the most suitable one automatically, but, again, it does not. Instead it's up to the developer to describe to the browser under what circumstances the different sizes should be used, using media queries.

I haven't specified any media queries in my code, just a single auto value, which acts as a default fallback rule. This will pick the image size best matching the full width of the image's parent element, which works well for me, as all of the (very few) images I use on this site are intended to be displayed across the full width of the page. With more varying image sizes I guess the ideal solution would be to set breakpoints for each individual image, but since my main motivation here is lazyness, I prefer a decent catch-all solution to a perfect one requiring a lot of manual work.

Fine-tuning

Using the above code, the responsive image generation just worked. I then proceed to add a couple of very optional extras to my configuration, specifically loading: "lazy" and decoding: "async". This improves initial page load speed, since the loading of off-screen images can be deferred until the user scrolls down to them. Having these attributes on all images is a bit of an anti-pattern, since images near the top of the page should ideally be loaded in-line rather than asynchronously. However, most of my images tend to be near the end of the post, so I don't feel too bad about adding the attributes.

They are added to the defaultAttributes, which are inserted into all generated <img> tags:

defaultAttributes: {
    sizes: "auto",
    loading: "lazy",
    decoding: "async"
},

Another small detail I've changed is the naming of the scaled images. This can be controlled by specifying a custom filenameFormat function. I know I can safely do this on this specific site, since I keep all post-related images in the directory of the post, but read up on it and make sure you pick a format that works for your site without causing any duplicate names:

const path = require("path");

...

filenameFormat: function (id, src, width, format) {
    let filename = path.basename(src, path.extname(src));
    return `${filename}-${width}.${format}`;
},

So, all in all, my configuration looks like this:

eleventyConfig.addPlugin(eleventyImagePlugin, {
    // The image formats to generate, in order of preference
    formats: ["avif", "webp", "auto"],

    // The images sizes to generate
    widths: [368, 736, 900],

    defaultAttributes: {
        sizes: "auto",
        loading: "lazy",
        decoding: "async",
    },

    filenameFormat: function (id, src, width, format) {
        let filename = path.basename(src, path.extname(src));
        return `${filename}-${width}.${format}`;
    },
});

Result

The output of the above configuration means a simple Markdown image like this:

![My image](./image.png)

Turns into this HTML:

<picture>
    <img loading="lazy" decoding="async" src="/.../image-368.png" alt="My image" width="900" height="762" srcset="/.../image-368.png 368w, /.../image-736.png 736w, /.../image-900.png 900w" sizes="auto">
    <source type="image/avif" srcset="/.../image-368.avif 368w, /.../image-736.avif 736w, /.../image-900.avif 900w" sizes="auto">
    <source type="image/webp" srcset="/.../image-368.webp 368w, /.../image-736.webp 736w, /.../image-900.webp 900w" sizes="auto">    
</picture>

In this example, the image is located in the same directory as the post, which is the structure I'm always using. The truncated path is the path of the post, e.g. /posts/my-post/. You can control the output location of the Image plugin using the urlPath option, but I prefer keeping the images with the rest of the post.

Another thing that might be good to keep in mind is that the image pre-processing will find all images in your pages, even e.g. the little header image on this site. That one I've already optimized manually, and I like to keep it as it is. You can both override certain parameters as well as have specific images be ignored entirely by the pre-processor using special parameters on the HTML elements themselves. For example, to have the Image plugin ignore my header image, I've added the eleventy:ignore parameter to it, like so: <img eleventy:ignore ... />. Check out the Image plugin documentation for the full specification.

Conclusion

It seems like with every release of Eleventy or its plugins, a customization I've built for this site becomes redundant, and I couldn't be happier about it. Even though the above solution does exactly the same thing as my previous one, I feel more comfortable using the same functionality from an official plugin. It also means that it will be maintained and keep working with future Eleventy versions.

If you want to read more about the ways I'm using Eleventy on this site, I've collected all my posts on a separate Eleventy page. Happy blogging!

My bicycle

Martin Gunnarsson — Sun, 25 Feb 2024 10:48:42 +0000

My bicycle is a silver Skeppshult STC Basic from 2005 or so. I don't remember exactly when I bought it, but I think it was around that time. Skeppshult is a Swedish manufacturer of bicycles founded in 1911. They've been making bicycles at the same location without interruption since then, and they're the only Swedish manufacturer that makes frames in-house. Iron, and later steel, has been very important resources in Sweden for centuries, and Swedish steel is world-famous for its strength and quality. It feels pretty cool then that the frame of my bike and the entire supply chain of raw materials needed to make it are extracted, refined, and produced within the borders of our little country. I'm sure pretty much all the other parts on the bike are made in China though, that's pretty much unavoidable these days.

The bike is probably best described as a "city bike", and has a pretty upright riding position. It has a Shimano Nexus 7 internally geared rear hub, a Shimano dynamo front hub with internal breaks, and pretty narrow, straight handlebars. It doesn't have any rack, which gives it a very clean look, but it does have mudguards on both wheels. Removing those would give the bike an even cleaner profile, but in this case practicality wins.

The hub dynamo was not part of the bike as presented in the catalog, but was custom made for me at the factory. Skeppshult assemble their wheels in-house, so I could get the correct rim, matching the rear one, but with a hub dynamo instead of the original one. I also asked for a metal chain guard instead of the ghastly transparent plastic one the bike was supposed to come with. I was pleasantly surprised that this level of customization was possible directly from the factory, and even more so that the man at the bicycle shop didn't seem to think it was anything out of the ordinary. The customizations were surprisingly cheap as well as I recall it, so the whole ordering process was a very positive experience.

I've been very happy with the bike since the day I got it. A difference I noticed from other bikes I've had was that it didn't make any sounds running on uneven surfaces like cobbled streets (of which we have plenty in the area). No rattling and no squeaking, very pleasant. Nowadays I get the occasional clank from the chain if I run over a bigger bump, but putting a little more tension on it would solve that. The rest of the bike is still rattle-free even after all these years.

I've ridden it to work from time to time and used it to get some exercise here and there, but I can't deny that it's mostly been stainding still. During a majority of the years I've had the bike, I've kept it outdoors, exposed to the elements. A few parts have gotten a bit of surface rust, but all in all it seems to cope pretty well with the Swedish climate. I've replaced the saddle, and when the original chain started getting rusty I replaced it with a stainless steel one. I've also replaced the tiny, cheap rear light a couple of times, but that's it for major maintenance I think. At least up until this year.

Recent modifications

Ahead of my bicycle commuting premiere I replaced the old, broken, halogen front-light with a new LED one. If I were to just order one online I would most likely have gone for a Busch + Müller one, as they have a wide range of high-quality dynamo lights in various designs, made in Germany. This time I had a city gift card that I got from work for Christmas that I wanted to use, and ended up buying a Spanninga Axendo 40 from a local shop. It certainly isn't the best looking light I've ever seen, and I did hesitate a bit before giving in and letting destiny guide me.

When it was time to buy the rear light I didn't have any gift card limiting me to certain shops. Instead the biggest constraint was my bike's lack of a rack. The vast majority of rear lights available are made to be mounted on the back of a rack. With that option removed, ideally I would have liked a light mounted to the saddle post or even saddle rails, but I couldn't think of any good looking way of routing a cable up there. After a bit of digging around I ordered a Busch + Müller Secula designed to be mounted on the wheel strut.

Both lights were easy to install on the bike, and they also seem to work well together. My dynamo is a bit underpowered at 2,4 W, but they shine steadily even at very low riding speeds.

In addition to installing the lights, I also replaced the gear-shift cable and its housing, which was cracked and rusty.

I might add a rack to the bike in the future, but I'll probably go for a minimal low-rider front pannier rack or something, to make sure the bike is still as impractical as possible. We've lived in a house for a couple of years now, with a nice and comfy garage for the bike to sleep in, so I hope we have many years (and kilometers) together ahead of us.

Bicycle commuting premiere

Martin Gunnarsson — Sat, 24 Feb 2024 06:15:42 +0000

Background

A while back I convinced myself bicycle commuting was a feasible alternative to driving for me, and started preparing to giving it a go. The plan wasn't to give up driving entirely, but to start going by bike maybe once per week or so, to introduce some much needed exercise into my life.

My preparations mostly consisted of some light bicycle maintenance, installing new lights and replacing the gear shift cable and housing, as well as browsing for racks and panniers and drooling over the beautiful photography over at Bikepacking.com. I also started using the bike to run errands in the village where we live, but the weather felt a bit too rough still to start commuting by bike. Of course I could have done it, it was by no means impossible, but part of my plan was to make at least the first few rides a positive experience, to lay the foundation for a new habit. The weather remained pretty bad for a while, then the entire family got the flu, and a few more weeks passed.

Just do it

Once I felt recovered and ready to give bicycle commuting a go, spring was in the air, and most days the weather was pretty decent. Ironically the days were also long enough that I wouldn't need my newly installed bike lights for the commute, but having them surely doesn't hurt.

Reviewing the weather forecast early in the week, the Friday looked like a good day to start. It was going to be windy, but no heavy rain like on the previous days. I don't have any rain clothes, so rain is currently a bit of a hindrance.

Reading the news the night before my maiden voyage, I saw warnings for storm gusts along the coast, which put my plans in jeopardy. Friday morning was indeed pretty windy, but the weather app on my phone showed winds from the south the entire day, which means a crosswind both ways of the commute. Battling a really strong headwind in either direction would probably have been a bit too much for my first attempt, but crosswinds I could live with. Also, I had sort of set my mind on going, and I was excited to finally give it a try.

During my research phase I thought a lot about a perfect setup, with panniers for my computer, spare clothes, a towel etc, and maybe even a bike trailer to take the kids to preschool. On the other hand, I knew that if I had to have all of that in place before riding to work, it would probably never happen.

So, I cleared my mind of all the cool adventure bikes from the internet and just put my computer and notepad in my trusty backpack, chucked a spare t-shirt in there for good measure, and that was it for packing. I dropped the kids off at preschool using the car, and then drove home and changed vehicles.

Departure

And just like that, I was off. We live at the top of a hill, so heading out on the bike is always easy. Still, even going down the steepest part of the hill I could feel the wind holding me back. This could be challenging.

I tried not to push too hard, as I didn't want to arrive at the office all sweaty. At the same time I didn't want my commute to take too long, since I had a pretty busy day ahead of me. I found a pace and cadence that felt sustainable without being too slow, and just chugged along. The first 2/3 of the distance is a very straight bike path across open fields, and the wind was always present but actually not that annoying. It slowed me down I'm sure, but it didn't stop me.

One stretch of this open part of the commute felt surprisingly boring. I first thought it was because there were no good mental milestones in sight. You could see pretty far ahead, but there was nothing to look forward to. When I drove into town with the family the day after I could clearly see that the boring part is also slightly uphill, and I'm sure that contributes to the tediousness. Still, it's only an 11 km commute in total, so it's by no means endless. Once I had pedaled through the boring part and pushed up a short but somewhat steep hill, I found myself in the city. Here I expected to be slowed down by traffic lights and other people in general, but I had an almost comically good timing with the traffic lights and hardly had to slow down at all. At this point my legs were letting me know that they were not used to this much pedaling, so I probably wasn't going very fast anyway.

Arrival

After exactly 40 minutes I arrived at work. I haven't timed my car commute (which includes a ~10 minutes walk from the parking garage), but I did get to the office a little bit later than usual. Maybe on a day with less wind the ride would have been a bit quicker, but the biggest time saver in the long run is probably just getting used to the commute and getting more fit.

I wasn't sweaty after the ride, so once I got into the office I could just grab a cup of coffee and get to work as I always do. This very good, as a change of clothes or a shower would have made the bike commute less viable from a scheduling perspective.

Heading home

Last summer I did a test-ride, going almost all the way to work and then back home again in one go. On that day my legs were getting pretty sore on the way back, but with an entire working day between the ride there and the one home, my legs would have had plenty of time to recover, right? Wrong.

Jumping on the bike in the afternoon my legs started complaining almost immediately, and the ride home felt much tougher even though the crosswind had shifted slightly to give me a tiny bit of tailwind.

Going up the steepest part of the hill up to my village, I acutally jumped off the bike and walked a couple of hundred meters. I could have made it on the bike if I really wanted to, but I'd rather take a short break and get home with a positive impression of the adventure. Again, building a new habit is the long term goal here.

Conclusion

Commuting by bike is a very feasible alternative for me. With some good rain clothes and waterproof shoes I could probably ride in almost any weather without too much hassle, but I'll try to stick to nice days to begin with. I'm very happy that I just got going instead of waiting to have the perfect gear and perfect weather. It was a bit risky to get sucked into articles and videos about bikepacking and adventure bikes when in reality I have very modest needs. It's not like I'm crossing the African continent or anything, I'm just riding my bike to work.

I'm not opposed to the idea of upgrading my equipment, but doing it after a number of rides makes for a much more informed decision. It's also very satisfying to buy something that you know will improve your life, rather than spending a lot of money upfront and then ending up with half of the stuff gathering dust in some closet anyway.

I'll try to commute by bike at least once per week, and I'm pretty tempted to do it on Monday already. I'm also well aware that I have a tendency to overdo things in the beginning, so taking an extra rest day or two certainly won't hurt.

The ride was a bit tough, but it was a very positive experience all in all. I could see myself going all-in on bike commuting in the future, but we'll see. A little bit is certainly better than nothing.

Local links in Eleventy, Part 2

Martin Gunnarsson — Wed, 14 Feb 2024 05:58:42 +0000

Background

The only thing I didn't like about Eleventy when I started using it was that local Markdown links, like /posts/my-post.md wasn't automatically transformed into their rendered URL counterparts, like /posts/my-post/. Having links pointing to the source files allows you to follow them locally when working with the content, and many Markdown editors can both help autocomplete links as you type as well as highlight any broken ones. For me, however, the most important benefit of working this way is that the content can remain unaware of the output format, so to speak. The less site details there are in the content, the more portable that content will be.

A while back I wrote a post about how to maintain working local links in Eleventy, and have them automatically transformed into the correct corresponding URLs at build-time. After publishing that post, I got a comment from Eleventy author Zach Leatherman, acknowledging that the current behavior isn't optimal, and that the issue would be solved in Eleventy 3.0.0. Delivering on that promise, Zach has now introduced the updated behavior as part of Eleventy 3.0.0-alpha5, yay! If you're ready to jump aboard the 3.0.0 train, here are some good, official directions to follow.

New times

My own solution to this problem was to implement an Eleventy Transform that replaced all local paths in links with rendered URLs. The official solution comes in two parts, a plugin and a filter, and the plugin uses a similar approach to mine. It's always nice to see you've gotten something right as a beginner, so that felt validating!

The plugin

The new Eleventy behavior comes as a bundled plugin called InputPath to URL that is optional and turned off by default. It can be enabled with a couple of lines in .eleventy.js:

import { InputPathToUrlTransformPlugin } from "@11ty/eleventy";

export default function(eleventyConfig) {
  eleventyConfig.addPlugin(InputPathToUrlTransformPlugin);
  
  // Further configuration ...
};

Once activated, the plugin will replace all references to local paths with their URL counterparts. My own link transformer only dealt with a[href], but the InputPath to URL plugin also transforms audio[src], img[src], [srcset] and a few more.

The filter

In addition to the above plugin, the new Eleventy release provides a filter called inputPathToUrl, that offers the same URL-remapping functionality. Here’s a Nunjucks example:

<a href="{{ "/posts/my-post.md" | inputPathToUrl }}">My post</a>

The above will be rendered as:

<a href="/posts/my-post/">My post</a>

Conclusion

I think my own link transformer turned out pretty good, but it’s still a relief to remove custom code in favor of a common solution. Packaging the functionality as a plugin is tidier than explicitly configuring a transform, which I previously did. The next time I want to customize something in Eleventy, I’ll probably use that as an excuse to try implementing a plugin of my own.

I’m very grateful that Zach picked up this old issue, Eleventy just keeps getting better and better. I can also happily report that the migration of this site to Eleventy 3.0.0 required only very minor changes. Check out the plan for the 3.0.0 release for more details about what’s included.

And lastly, if you want to read more about Eleventy, I've created a page with all my Eleventy posts, so that you can follow along on my adventures.

Happy blogging!

Making a case for commuting by bike

Martin Gunnarsson — Thu, 18 Jan 2024 06:03:42 +0000

I live 11 km from work, and there are excellent bike paths all the way, yet I commute by car. I've successfully made several small but positive changes to my life in the last few months, and I would like to take on my habit of commuting by car next. I'm not looking to change it completely, but at least soften it up a bit. I have a colleague and a neighbor who frequently commute the same route as me by bike, so I know it's both physically and practically possible.

This post is mostly a way for me to start considering biking to work as a realistic option, rather than a theoretical possibility, but I hope it can also inspire others to change up their daily commutes.

Pros

The biggest benefit of biking to work (by far) would be getting exercise and fresh air. I spend much of my working day sitting, either at the computer or in different meeting rooms. By driving to work I waste a great opportunity to fit exercise into my busy schedule and add some more sitting instead. No good. Starting the day with a decent bike ride would most likely improve my workdays in many ways as well.

For my current commute, I drive an electric car that I charge at home, which is cost-effective compared to some other car types. Still, biking is free, and every day I choose the bike instead of the car I would work towards lowering our electricity bill.

Another driving-related expense is parking, but here the savings aren't as clear-cut. In the parking garage I use, parking a single working day costs a little more than 100 kr (which at the time of writing roughly equals $10). That's not what I pay though, as there are also monthly permits for 750 kr, which is a very good deal for me since I drive to the office pretty much every weekday of the month. Come to think of it, I get more value out of a monthly permit the more I drive that month, which is not great motivation. To save money on parking by driving less, I would have to drive a lot less. On paper, this looks like an added incentive to take the bike, but in reality, I find the pressure off-putting. I would rather bike because I enjoy it than because I "have to".

Cons

I live in southern Sweden, and it’s almost always windy here. Most of my commute is across open fields without any cover from the wind. Some days it probably wouldn’t be that pleasant to be a bike commuter here, if I'm being honest. I would need some flexible rain clothes in order not to arrive at work completely soaked on rainy days, but depending on how hard I have to pedal I might need a change of clothes (and perhaps even a quick shower) after the commute anyway.

Previously I parked at a garage closer to work, but that meant more time-consuming driving through the city center as well as a substantially higher parking fee. The change to my current garage reduced my drive by 5-7 minutes but introduced a ten-minute walk instead. Before making the change I had the same concerns about the weather as I do regarding the bike commute now, but in reality, it hasn’t been a problem at all. Chances are that the bike commute too would be less of a problem than I think.

In any case, clothes for the day may have to be brought along, and so would my briefcase or other bag with my computer, notepad, and various other small items. All of this would have to be well-protected from the elements and carried comfortably. My bike has no rack either front or back, so a backpack is the most straightforward option. I'm not thrilled by the idea of biking back and forth with a backpack every day, so this is an area I would like to explore more.

The biggest problem I have to solve to make the bike commute work in practice is dropping off the kids at preschool. We have a two-year-old and an almost-six-year-old, and I currently bring them to preschool every morning as part of my drive to work. I think our son, the almost-six-year-old, could ride his own bike there without a problem, but then there are those mornings, when everything has the potential to cause a meltdown. Those mornings would not be pleasant if he had to make it there under his own power, and I would have to have an alternative solution in place from the beginning.

There are two good options the way I see it: getting some kind of long-tail or cargo bike with room for two kids, or getting a bike trailer. Utility bikes like that are really cool, but a trailer is the most sensible option in every way. They are much cheaper than a utility bike and could be detached and left at the preschool for when my wife picks the kids up in the afternoon. Many bike trailers can also be pushed like a stroller, so she could use it with or without her bike. Regardless, leaving the extra bulk behind before crossing those windy fields would be a big relief!

I guess there's also the option of driving the kids to preschool and then going back home and switching to the bike. It feels unnecessarily complicated and time-consuming, but could be a way of getting started without any new gear at all, or work as a last resort on difficult days.

Time

Time is, perhaps surprisingly, an aspect of the commute I haven't thought that much about yet. I think driving from the preschool to the parking garage takes roughly 25 minutes depending on traffic, and walking from the garage to the office takes about 10 minutes on top of that.

Last summer I tried riding my bike to the city and back just to see what it was like, but on that day I didn't have time to go all the way to the office. Starting at our house, the part of my commute covering the countryside and city outskirts took 18 minutes on a day with unusually calm wind. The rest of the commute into the city center would be slowed down by traffic lights and people in general, so even though I went more than half the distance in those 18 minutes, the remainder could easily take just as long. As mentioned I also started from our house rather than from the preschool, and I'm not sure how that affects the time. The preschool is located on top of a pretty steep hill, so going there by bike will also take much longer (relatively speaking) than doing so by car.

All in all, the car will likely be faster in the end, but perhaps not by that much. The potential need for a change of clothes after biking would also take some time, which must be taken into consideration. I'm prepared to spend slightly longer on my commute to get all the benefits of biking, but not too much. My days are already unnecessarily tight, and I often work a bit at home in the evening to compensate for not reaching a full workday at work. If possible I would like to avoid adding to this part of my day.

Conclusion

Commuting by bike is a realistic option for me, and by writing this post my mind is set on giving it a try. As mentioned, I could start off with what I have in the beginning, but there are some investments I could make to ensure the transition is as practical and friction-free as possible:

Getting a bike trailer
Getting a helmet
Getting rain clothes
Minor bike fixes/maintenance

None of these are huge expenses, and even if it would take a while to make the money back by not driving, the benefits are clearly worth it. Also, buying gear is great fun when you have such a good reason for doing so!

Additional investments could be:

Adding some kind of rack to my bike
Getting a waterproof bag for said rack
Getting a good bike phone mount

The phone mount is the least important thing on this list, but I know that numbers, analytics, and charts motivate me, so it could be an additional incentive.

First steps

My plan is to not aim too high, but to start off by taking the bike some days. Like, the sunny ones, when there aren’t any gale-force winds. On the other hand, I’ll also make sure not to wait for perfect weather either, because then I'm never going to get started.

This is a whole new area of my life to geek out about, and I have to say the challenge itself is very exciting! The roads are pretty snowy and slippery now, but as soon as conditions improve just a little, my mind is set on making a test run without any new equipment, etc. just to see how it feels, how much time it takes, and whether there are any unexpected pros or cons. I'm looking forward to this new adventure!

Right here, right now

Martin Gunnarsson — Sun, 07 Jan 2024 21:51:42 +0000

One day while reading a blog post I noticed the blog had a "Now" page, where the author briefly described what they were up to at the moment. Unfortunately, I can't recall the specific blog, but it did link to Nownownow.com, which is a page by Derek Sivers promoting the concept of the Now page. Two things stuck with me: Derek seemed to be a very interesting person, and as someone with periodic "flavor of the week"-style obsessions, the Now page concept was very appealing to me.

Derek compares the Now page to an About page (albeit a less static one), an auxiliary page with an easy URL that tells visitors something about the author. I used to have an About page, but as part of the rewrite of this blog, I turned it into a section on the homepage instead. This eliminated the need for any menu or other navigation elements, and to avoid adding any back solely for a Now page, I decided to include that too as a section on the homepage.

An unsatisfactionary attempt

I could have simply added a paragraph to the homepage and updated that as needed, but my mind rarely lets me get away that easily. I knew I wanted to keep a record of the history of my Now content one way or the other, perhaps to list it as a timeline of sorts in the future.

My first attempt was having the content as a separate file, rendered as part of the homepage using the Eleventy Render plugin. The plugin is included with Eleventy, and can be activated in the .eleventy.js:

const { EleventyRenderPlugin } = require("@11ty/eleventy");

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(EleventyRenderPlugin);

  // Further configuration ...
};

With the plugin activated, you can render any Eleventy template from any other template like this:

<article>
    {% renderFile './_includes/now.md' %}
</article>

This worked fine, and I got an automatic file history in Git. However, that isn't the most accessible place if I would like to list previous entries on the site in the future.

Round 2

One night as I was falling asleep I realized that my Now content should of course be treated like any other content in Eleventy. This would probably have been obvious from the beginning if I had a little bit more Eleventy experience, but it took some time for the penny to drop.

Content

Eleventy is highly flexible regarding content. You can have different types of content for different purposes, located anywhere in the file structure, and you have a lot of control over the behavior it all.

For my Now content, I had a fairly clear idea of what I wanted:

A list of tiny Markdown files in a separate directory, to keep things tidy.
An Eleventy collection of that content, sorted by date.
Prevent the content from being rendered into individual pages.
Keep the files clear of any frontmatter or other metadata.

I created a directory called now, and added my first post called 2024-01-04.md, for lack of a better name. Even though I didn't want any metadata in the files, I still needed to specify at least two pieces of information for each of them: a tag to keep the content organized in a collection and a date to have them sorted correctly.

Automatic tagging

Since the Now posts live in a directory of their own, I knew I could utilize the Data cascade in Eleventy, and add a directory data file that applies common attributes to all files in that directory. Directory data files should be located inside their respective directories and named following the pattern [directory name].11tydata.[format]. Following this convention, I created a file named now.11tydata.json in my now directory, containing a single property:

{
    "tags": "now"
}

This little snippet assigns the now tag to all posts in the now directory. As a resuly, they'll be accessible as collections.now in Eleventy.

Excluding content from rendering

With a small addition to the directory data file, I could also disable the content from being rendered into individual pages:

{
    "tags": "now",
    "permalink": false
}

The permalink property can be set to a pattern telling Eleventy where to put the pages rendered from each post. Setting it to false means no rendering will take place at all.

Dates

As mentioned, I also wanted to set the date of each post somehow, both for my historical records and to be able to display the latest post on the homepage. I was prepared to implement some kind of computed property setting the date based on the filename. To have something to work with, I added a couple of more posts to the now directory. To my surprise, they automatically appeared in the correct order. Was this just a fluke, or some clever feature in Eleventy? A bit of both, it turns out!

The Content Dates section of the Eleventy docs held the answer. Eleventy goes to great lengths to find a date for each post. You can specify one in different ways, but ...

If a date key is omitted from the file, we then look for a YYYY-MM-DD format anywhere in the file path (even folders).

Clearly a very clever feature in Eleventy, but I also got lucky naming my files according to the one true date format, and that Eleventy looks for this very format as part of the file path. What I expected to be the trickiest part of this setup turned out to work straight out of the box. Sweet!

Rendering

With the now collection sorted (*badum-tss*), all I had to do was to include the latest post from it on my homepage. I already do this with my latest post post, so this part was easy:

{% set now = collections.now | last %}
<article>
    <h2>Right now</h2>
    {{ now.content | safe }}
</article>

The latest post in the collection is picked out using the last filter. The content of the post can then be accessed using the now.content property. The safe filter inserts the content of the post as-is, without any escaping of special characters.

The same thing can be written as a shorter but less readable oneliner:

{{ (collections.now | last).content | safe }}

Conclusion

The solution to my problem turned out to be quite straightforward, perhaps even too much so for a tutorial like this. However, I learned several things about Eleventy in the process, and I hope others will too.

My main takeaways are:

Eleventy is built to deal with content, and large amounts of it too. Any time you're working with a series of content, even if you just want to use something like the latest piece of it, consider using tags and the resulting collections before exploring other alternatives.
The Data cascade in Eleventy is both flexible and powerful, and directory data files are a convenient way to avoid repetition of metadata for content within a directory. In my case, leaving out the entire frontmatter section from my content files felt like a big win.
It's pleasing to see all the ways Eleventy tries to find a date for each piece of content, including inspecting the file path, and extra pleasing to see it's specifically looking for ISO 8601 dates.

Getting to know Eleventy has been a true delight, and this little project only strengthens my positive impressions of it. For those who want to know more, I've collected all my Eleventy-related posts for easy reference. I encourage anyone embarking on a web project to consider Eleventy. It's flexibility and user-friendlyness makes it a joy to work with!

The apps I use

Martin Gunnarsson — Thu, 04 Jan 2024 06:43:42 +0000

Episode 97 of the Hemispheric Views podcast, called Duel of the Defaults, set of quite a trend on the web. In that episode, Martin Feld and Jason Burk compete for the coveted "Mr. Default" title, by comparing the different apps they use, and deciding who is most default (according to arbitrary decisions by judge Andrew Canion). After this, people started listing their own "default apps", which is not quite what the show was about, but a fun thing to do nontheless. Robb Knight has collected many of these on his website, and allow people to add theirs using Git pull requests (which I did). I'm a bit late to the game with this, but better late than never!

Apps

These are the apps I use personally, i.e. not for work, on both my iPhone and Mac:

📨 Mail Client: Mail
📮 Mail Server: iCloud, with custom domain
📝 Notes: Notes, Obsidian
✅ To-Do: Reminders
📷 iPhone Photo Shooting: iOS Camera
🟦 Photo Management: Photos
📆 Calendar: Calendar
📁 Cloud File Storage: iCloud Drive
📖 RSS: N/A
🙍🏻‍♂️ Contacts: Contacts
🌐 Browser: Safari
💬 Chat: Messages (if that's considered chat), very occasionally Slack
🔖 Bookmarks: Some old bookmarks in Safari, nothing else
📑 Read It Later: Occasionally using the Reading list in Safari, but rarely read the things I put there
📜 Word Processing: N/A
📈 Spreadsheets: Google Sheets
📊 Presentations: N/A
🛒 Shopping Lists: Notes, a shared note with my wife
🍴 Meal Planning: N/A
💰 Budgeting and Personal Finance: Google Sheets, Zlantar
📰 News: N/A (I get news from websites and Mastodon, but don't use a specific news app)
🎵 Music: Apple Music
🎤 Podcasts: Apple Podcasts
🔐 Password Management: iCloud keychain, and a sprinkle of 1Password

Conclusion

When I started going through this list I was actually surprised by how "default" I am. I'm hardly using any non-Apple apps/services at all. Part of this is because I want to stay away from Google, but also that Apple services usually work pretty damn well. Of course, there are more powerful and advanced options for every single category, but I rarely need anything outside the ordinary for my daily business, so the default apps suit me well.

If you speak Swedish, or wouldn't mind hearing me and Fredrik Björeman doing so, we've recorded an episode of our podcast Synk on this very topic.

Automatic pre-processing of post images in Eleventy

Martin Gunnarsson — Fri, 29 Dec 2023 08:02:42 +0000

Background

When I moved this blog from Hugo to Eleventy I wanted to set everything up from scratch to be in control. No more massive themes with mysterious features you're afraid to change because you don't know the potential side-effects. That being said, I did look around at different Eleventy starters, like the Eleventy base blog, and took note of a few features to set up myself.

Since I was in full control of the site, getting good performance was surprisingly easy, resulting in a perfect score from the Lighthouse analyzer in Chrome. While working on the site I would occationally run the analyzer again, to make sure the score hadn't deteriorated. One single post always failed, since it had a massive image in JPEG format that I just hadn't bothered to resize manually. Ideally I shouldn't have to, either. This was a perfect use case for some Eleventy automation!

Plugins

I was already aware of the official Image plugin for Eleventy, which can take a source image and generate copies in various sizes and formats. It's using the Sharp image processor for Node under the hood. I'm very familiar with this, so writing a similar feature from scratch would probably have been very doable. However, it's very comfortable to just use a proven implementation when available.

What did surprise me a little was that the Image plugin works exclusively with a custom shortcode, rather than regular Markdown images. I write all my posts in Markdown, and I wanted to have all images automatically pre-scaled in various formats, so that visitors could get the best quality and performance for their device. So, I had the Eleventy Image plugin, and I knew the Markdown processor used in Eleventy, markdown-it has good support for plugins, to alter the behavior of certain elements. I just had to tie it all together. Things were looking promising!

By pure chance I then stumbled upon the markdown-it-eleventy-img plugin for markdown-it, that does exactly what I was just about to do myself. The thought of something like this already existing hadn't even crossed my mind, and I got that familiar feeling of relief mixed with disappointment that arises when a challenge is taken away from you. Of course I could still have written my own implementation, but in this case the goal was more important to me than the journey itself.

Configuration

Time to get everything set up! First I installed the markdown-it-eleventy-img plugin using npm:

npm install markdown-it-eleventy-img --save-dev

Then I added it to my .eleventy.js configuration file:

const markdownItEleventyImg = require("markdown-it-eleventy-img");

module.exports = function (eleventyConfig) {
    eleventyConfig.amendLibrary('md', mdLib => mdLib.use(markdownItEleventyImg, {
        imgOptions: {
            widths: [368, 736, 900],
            formats: ['auto', 'webp', 'avif'], // Don't do this, see below
            outputDir: '_site/assets/images/scaled',        
            urlPath: '/assets/images/scaled'
        },
        globalAttributes: {
            sizes: '100vw'
        }
    })

    // Further configuration ...

    return eleventyConfig;
}

I'm using the amendLibrary function to add the plugin to the markdown-it instance already in use in Eleventy. In addition to the plugin itself, I also supply a tiny bit of configuration. Here I specify the image widths and formats I want to generate, and specify both where I want the resulting files to be saved and what URL path this corresponds to.

Lo and behold, it worked!

An image in a Markdown post like this:

![An image](/assets/images/image.png)

Used to be converted into a regular image tag:

<img src="/assets/images/image.png" alt="An image">

But now, it resulted in a whole buffet of images for the browser to choose from:

<picture>
    <source type="image/png" srcset="/assets/images/scaled/FR-0A22Z5T-368.png 368w, /assets/images/scaled/FR-0A22Z5T-736.png 736w, /assets/images/scaled/FR-0A22Z5T-900.png 900w" sizes="100vw">
    <source type="image/webp" srcset="/assets/images/scaled/FR-0A22Z5T-368.webp 368w, /assets/images/scaled/FR-0A22Z5T-736.webp 736w, /assets/images/scaled/FR-0A22Z5T-900.webp 900w" sizes="100vw">
    <source type="image/avif" srcset="/assets/images/scaled/FR-0A22Z5T-368.avif 368w, /assets/images/scaled/FR-0A22Z5T-736.avif 736w, /assets/images/scaled/FR-0A22Z5T-900.avif 900w" sizes="100vw">
    <img alt="An image" src="/assets/images/scaled/FR-0A22Z5T-368.png" width="900" height="900">
</picture>

Problems

Even though my first test was successful, I immediately noticed a few problems as I started clicking around the site:

Large images, while shrunk to fit the page width, didn't have their height shrink proportionally, resulting in a stretched appearance.
I have my post images located in the same directory as the post, e.g. /posts/my-post/index.md may be using /posts/my-post/image.png by just referring to it as ./image.png, and these couldn't be found by the plugin.
The browser still loaded the much larger JPEG or PNG file even though I was offering delicious WEBP and AVIF versions.

Scaling proportionally

I'm still not entirely sure why the images wouldn't scale proportionally automatically, but I think I may have caused it myself. Before I had any image scaling in place, I was just using CSS to make sure the images fit within the page:

article img {
    max-width: 100%;
}

With the new setup, the img element automatically received width and height attributes. It seems like browsers set the image width according to the max-width CSS rule and the height based on the height property. The solution was to add a CSS rule for the height as well:

article img {
    max-width: 100%;
    height: auto;
}

It feels like I might be missing something here, but this workaround has consistently solved the problem in all browsers I've tested.

Post-relative images

As I prefer to keep post images in the same directory as the post itself, avoiding a large central collection of images with unclear usage, the issue with the markdown-it-eleventy-img plugin not finding theses was a showstopper. Fortunately, the solution was very straightforward, as the plugin offers full control over where to look for different images using the resolvePath option:

const path = require('path');

eleventyConfig.amendLibrary("md", mdLib => mdLib.use(markdownEleventyImg, {
    imgOptions: { ... },
    globalAttributes: { ... },
    resolvePath: (filepath, env) => {
        let isPostImage = filepath.startsWith('./');
        if (isPostImage) {
            // Resolve path to post-relative images
            return path.join(path.dirname(env.page.inputPath), filepath);
        } else {
            // Resolve path to global images
            return path.join('_site', filepath);
        }
    }
}));

I always refer to images relative to posts using paths beginning with ./, which makes them easy to identify here. While I don't currently use any "global" images in my posts, I didn't want to break that functionality. I'm using the Node path library to piece together the paths needed for the two different use cases. Additionally, I've noticed it's sometimes necessary to clean the previous build for the image plugin to work correctly. This is likely since it attempts to avoid regenerating images that already exist. If you encounter weird problems building your site after changing the image configuration, try cleaning the site by deleting the _site directory, and then rebuild it.

Modern file formats not used

With everything else working, it was perplexing to see that all browsers consistently favored the original PNG or JPEG format over of the significantly smaller modern alternatives. What gives! Like so many times before, an assumption turned out to be the source of the problem. My image format specification was set as ['auto', 'webp', 'avif'], with auto representing the original format of the source image. I had presumed that browsers would automatically select the best format they supported, but this feels somewhat naïve in retrospect. In reality, browsers simply pick the first format they support. While I had subconsiosly arranged the formats based on their likelyhood of support, I should in fact have used the exact opposite: ['avif', 'webp', 'auto']. With that little change, Safari, Firefox and Chrome all picked the AVIF file, and there was much rejoicing.

Further improvements

Finally, I was poised to bask in the accolades of the Lighthouse analyzer for my post featuring that large image ... right? Unfortunately, not quite. The post in question is pretty long, and the Lighthouse report complained I should defer loading of the images until the user scrolled down a bit. Fair enough. I skimmed through the official Lighthouse documentation of the issue, which was rather unhelpful. The linked codelab on lazy loading images quickly delved into JavaScript solutions, which I very much wanted to avoid (on the client side).

Fortunately, there are better options. Modern browsers support the loading="lazy" property for images, as well as decoding="async" to further optimize for rapid page rendering. To my delight, the image plugin allows for any arguments to the image tag to be specified in the globalAttributes configuration option:

eleventyConfig.amendLibrary("md", mdLib => mdLib.use(markdownEleventyImg, {
    imgOptions: { ... },
    globalAttributes: {
        sizes: '100vw',
        loading: 'lazy',
        decoding: 'async'
    },
    resolvePath: (filepath, env) => { ... }
}));

It's so satisfying to observe the network panel in the browser development tools and see the images load automatically as you scroll down the page. Finally that post got a perfect 100/100/100/100 score in Lighthouse, just like the rest of this site!

Conclusion

After all the modifications above, my final markdown-it-eleventy-img configuration in .eleventy.js looks like this:

eleventyConfig.amendLibrary('md', mdLib => mdLib.use(markdownEleventyImg, {
    imgOptions: {
        widths: [368, 736, 900],
        formats: ['avif', 'webp', 'auto'],
        urlPath: '/assets/images/scaled',
        outputDir: '_site/assets/images/scaled'
    },
    globalAttributes: {
        sizes: '100vw',
        loading: 'lazy',
        decoding: 'async'
    },
    resolvePath: (filepath, env) => {
        let isPostImage = filepath.startsWith('./');
        if (isPostImage) {
            // Resolve path to post-relative images
            return path.join(path.dirname(env.page.inputPath), filepath);
        } else {
            // Resolve path to global images
            return path.join('_site', filepath);
        }
    }
}));

Using this configuraion, everything has been functioning beautifully so far. Since I don't frequently use images in my posts, it remains to be seen if any issues will aries in the future. I'm very happy that I found the markdown-it-eleventy-img plugin, and that it's been so flexible to work with. Kudos to the author, Mathieu Huot, very impressive work!

For those who want to read more about Eleventy customization, I've created a page listing all my Eleventy posts.

Customizing external links with Eleventy

Martin Gunnarsson — Tue, 26 Dec 2023 19:23:12 +0000

Background

I've recently written a couple of posts about the different ways I've customized the Eleventy, the static site generator used for this site. In the previous post I described modifying the HTML rendered by Eleventy to maintain working internal links between Markdown files. This modification makes Eleventy treat local links the way I believe it should by default. Next on my improvement wishlist was addressing the lack of visual distinction between internal and external links in my posts. With my successful link-transformation effort fresh in mind, I immediately set out to add some additional HTML post-processing.

Post-processing

In the post linked above I introduced a small class that iterates over all links in every page, modifying the internal ones, so in my case it was very straightforward to add another snippet to the same iteration. Here’s a standalone version of the code dealing only with the external links, which you can include in your .eleventy.js file:

const cheerio = require("cheerio");
const externalLinkSvg = '<svg>...</svg>';

module.exports = function (eleventyConfig) {

    eleventyConfig.addTransform("updateLinks", function (content, outputPath) {
        // Only apply this to HTML files
        if (!outputPath || !outputPath.endsWith(".html")) {
            return content;
        }

        const $ = cheerio.load(content);

        $('a[href^="http"]')
            .filter((_, a) => $(a).text().trim() != '')
            .each((_, a) => {
                $(a)
                    .append(externalLinkSvg)
                    .addClass('external')
                    .attr('target', '_blank')
                    .attr('rel', 'noopener');
            })

        return $.html();
    });

    // Further configuration ...

    return eleventyConfig;
};

The code utilizes Cheerio to parse the HTML content of the generated post. It specifically searches for all a elements with a href attribute beginning with http, as a crude way of identifying external links. Since I just want to modify text links (e.g. not image links, like the contact icons in the page footer), the matching a elements are then filtered to exclude those without text content. The remaining collection is iterated over using each(), and within this loop any desired customizations can be made. In this example, I append a small snippet of SVG right into the link content, add a CSS class, set the target attribute to _blank and rel to noopener just for good measure.

At the end, the modified DOM is returned in the form of HTML, and the work of the link transformer is complete.

An alternate approach

Instead of modifying the HTML produced by Eleventy, Jeff Sheets suggested I could use a plugin for the Markdown parser used by Eleventy, markdown-it, to generate the links the way I want them right from the start. This feels like a more refined solution, but I haven't been able to achieve the result I want using this approach.

There are multiple plugins modifying links in various ways, some (like markdown-it-external-link and markdown-it-external-links) are even specifically made to add additional attributes to external links. However, I haven't found any plugin that can both add attributes and append content, like the inline SVG icon I'm using, to the links.

There are several plugins that can add CSS classes to external links, and using CSS I could instead insert my SVG icon into the external links using the ::after pseudo-element like this:

a.external::after {
    content: url(/assets/external.svg);
}

But unfortunately this still won't work the way I want. The problem is that this site has a light and a dark mode, and the link color varies slightly depending on the mode. To ensure the external link icon matches the color of the link itself, I insert it into the link content as inline SVG. This in combination with the property fill="currentColor" in the SVG code makes the icon inherit the color of the parent element. Sadly this doesn't work when the SVG is inserted using the ::after pseudo-element. In fact, I haven't found any way to set the color of the SVG inserted this way using CSS, it seems like the only option is to set the color in the SVG file.

I'm tempted to add support for modifying the link content to one of the plugins mentioned above, but I'd have to check if the authors are interested in this first. Another option would be to build my own plugin, but this would merely move my custom code to a different file, and I don't feel that bad about my post-processing approach.

Conclusion

While modifying the output of the Markdown processing itself would be a better solution, adding transforms to modify the HTML produced by Eleventy is a good way to ensure your site comes out just the way you want. Using Cheerio for this task does bring back some memories of ... erm, less elegant jQuery hacks from the past, but it feels much better to have this type of code as part of a build step rather than live on a site.

For those who want to follow along on my Eleventy adventure, I've got a page listing all my Eleventy posts. I'm still learning Eleventy myself, but hopefully I can share some insights and lessons learned from setting up this site.

Happy tinkering!

Maintaining working local links in Eleventy

Martin Gunnarsson — Mon, 18 Dec 2023 16:10:42 +0000

Background

This is the second post detailing the different customizations I've implemented in Eleventy for this site. In the first post I briefly described setting up code syntax highlighting, which primarily involved installing and configuring an existing plugin. Another tweak I really enjoy is the way links are handled, and for that I had to write some code off my own! I've actually customized both internal and external links, each in different ways, but let's focus on the internal ones first.

Internal links

As I wrote in my earlier introduction to Eleventy, I very much appreciate the clean separation of content and presentation that Eleventy and many other static site generators provide. I write all content for this site in Markdown files, and ideally I would like to keep the contet free of any "knowledge" about the site. I've even considered managing it completely separately from the site's codebase, perhaps in Obsidian? This is mostly out of principle, but it also ensures that the content can easily be transferred to a different tool in the future, should the need arise. Having page metadata in the content front matter is very convenient however, and for convenience I'm willing to bend my principles slightly. I guess I'm more pragmatic than idealistic in the end.

As I was getting to know Eleventy, the only thing I was slightly disappointed by was the fact that local links between Markdown files aren't automatically transformed into their "online" format during page rendering. For example, a post called /posts/frogs.md will be rendered into a HTML page in the file /posts/frogs/index.html by default, and should be linked to as /posts/frogs/, but any Markdown links to this file remains unchanged as /posts/frogs.md. Consequently, for the links to function correctly on the rendered site, they must use the online format in the source files. This introduces precisely the kind of website-specific knowledge into the content that I want to avoid. It also means I have to make a choice between having functional links on the live site or within the Markdown files. It's an easy choice of course, but ideally such a compromize shouldn't have to be made. Additionally, having proper local links in the source files means text editors can help with autocompletion while writing them, which can be very helpful for long paths.

I decided to try to do something about this before filling up the site with too much content. First I reverted all the local links back to their original form, i.e. /posts/frogs.md in the example above. I then implemented an Eleventy transform to convert these into the appropriate online format. In Eleventy, a transform is a function that gets called after each page is rendered, allowing for post-processing modifications. They are typically configured in .eleventy.js:

const LinkTransformer = require("./_scripts/linktransformer");

module.exports = function (eleventyConfig) {
    eleventyConfig.addTransform("updateLocalLinks", function (content, outputPath) {
        return new LinkTransformer().transformLinks(content, outputPath);
    });

    // Further configuration ...

    return eleventyConfig;
};

LinkTransformer is a small class I wrote for this task. It utilizes Cheerio to traverse and modify the rendered HTML content, and replaces all local links ending in .md with the ones ending in /:

const cheerio = require("cheerio");

class LinkTransformer {
    transformLinks(content, outputPath) {
        // Only transform HTML pages
        if (!outputPath?.endsWith(".html")) {
            return content;
        }

        const $ = cheerio.load(content);

        // Iterate over all <a> tags
        $("a").each((_, link) => {
            const href = $(link).attr("href");

            // Replace '.md' with '/' at the end of the href
            $(link).attr("href", href.replace(/\.md$/, "/"));
        });

        return $.html();
    }
}

Conclusion

Being relatively new to Eleventy, I'm not entirely sure if this approach is the most straightforward, but no one would be happier than me if it turns out I've simply overlooked an obvious, built-in solution. In any case, I'm quite pleased with the results. Now I can follow links between my posts both locally in my text editor and online on the published site. It would be interesting to hear what the author of Eleventy, Zach Leatherman, would think about this modification. From a design principle standpoint, I believe maintaining functional local links is a better approach.

Update
Zach replied to me on Mastodon pointing out that this is an old issue in Eleventy and that he'll get it resolved in the upcoming 3.0.0 release 🤩

Next up I'll describe how I modified the tiny LinkTransformer class to also deal with external links, so stay tuned for that. I've also set up a page with all my Eleventy posts for those who want an easy overview of my Eleventy journey.

Another update
Zach has now implemented the solution to the aforementioned issue, and as of Eleventy 3.0.0-alpha5 you get this functionality as part of the package. I've written a follow-up post on how to use it.

Addendum

Out of curiosity I tried opening my posts directory in Obsidian, and to my surprise it presents the front matter in a very pleasant way. I just played around with it very briefly, so I can't be a hundred percent sure, but unfortunately it seems Obsidian only wants to autocomplete local links while creating special Obsidian links, so perhaps I'll stick to VS Code for now. Still, it made me even more curious about working with content fully separated from the code in the future.

Syntax highlighting code in Eleventy posts

Martin Gunnarsson — Sat, 16 Dec 2023 20:30:42 +0000

Background

This site is built using Eleventy, a very nice little static site generator. I've previously written a post about how and why I ended up using it, but that mostly covers how to get up and running with generic content. This is the first post in a little series outlining the different customizations I've made in order for Eleventy to produce just the result I want.

Syntax highlighting

One of the few features outside the basics I was looking for when I compared static site generators was syntax highlighting of code blocks. I often write about programming-related topics here, and having syntax highlighting makes any code snippets included much more pleasant to read. Luckily there's an official Eleventy plugin for that, which is using Prism under the hood. Prism has support for a long long list of languages (although I'm not sure whether all of them are included in the Eleventy plugin), and it seems to be both realizable and really fast as well.

There are three steps involved in setting up syntax highlighting:

Installing the plugin
Adding CSS for the code color scheme
Tagging your code blocks with the language used

Installation

The plugin is installed using npm:

npm install @11ty/eleventy-plugin-syntaxhighlight --save-dev

Once installed it's available in the local Node environment, and can be added to Eleventy with just a couple of lines in .eleventy.js:

const syntaxHighlight = require("@11ty/eleventy-plugin-syntaxhighlight");

module.exports = function (eleventyConfig) {
    eleventyConfig.addPlugin(syntaxHighlight);

    // Further configuration ...

    return eleventyConfig;
};

If you just want to get up and running, that's all there is to the installation step. You can also pass an options object to the addPlugin function to adjust the settings for the plugin as well, but I'm guessing the defaults are fine for most people.

Adding CSS

Now Prism will run, and automatically introduce some additional markup (a lot of <span> tags, to be precise) to the HTML produced from the code blocks, but to actually see any visible syntax highlighting you also need to include a Prism theme in your site. This is a small CSS file dictating the color and style of different elements of the code. There are plenty of themes to choose from, and if none of them suit your needs you can of course modify one, or create your own from scratch. Some of the more popular themes are available from various CDNs, but I decided to include mine as part of the site CSS.

Languages

After adding the CSS you're technically all set, but at this point I still wasn't getting any syntax highlighting. I'm not sure whether this is theme specific, but to finally see the colorized code in all its glory I also had to tag the code blocks with the corresponding programming language:

```html
<h1>Spatula City!</h1>
```

```css
body {
    background: lime;
    color: red;
}
```

```js
console.log("Hello world");
```

Please refer to the list of supported languages to see the what tag to use for different languages. If you're using a template language other than Markdown, please refer to the plugin documentation for how to utilize syntax highlighting.

Conclusion

I really like the syntax-highlighted code blocks and I'm very happy with the way this plugin works. I am however a little bit worried that the highlighting actually makes the code much less user-friendly for readers using text-to-speech devices, screen readers, and similar technologies. I'll have to investigate further to understand if this actually is a problem. Perhaps the fact that Prism only seems to inject <span> tags means it doesn't interfere with assistive technology. If it indeed is a problem I would really like to find an elegant solution to it, so if you happen to know more about this, please let me know.

Eleventy brings me joy

Martin Gunnarsson — Thu, 14 Dec 2023 21:13:14 +0000

Background

In the olden days, I had a completely custom site written in classic ASP and kept it up for many years, until social media platforms became my primary outlet for sharing thoughs online. I still built the occasional website for various endeavors, but moved gradually to more ready-made systems like Wordpress and Tumblr. It had been a very long time since I last had a personal website when a few toots on Mastodon inspired me to start blogging again.

A false start

A few years ago I built a very basic site for documenting my home brewing using Hugo, and liked the concept. Hugo is a static site generator - a tool that transforms content such as Markdown files into fully-fledged web pages by merging them with templates dictating layout and design. In certain generators the content can be any form of structured data, even sourced from APIs or databases on the fly, which makes maintaining a large number of pages very manageable without a lot of tedious manual work.

In my opinion the biggest benefit of static site generators lies in the separation of content and presentation. This allows for updating and improving (or even fully replacing) the design and layout of a site without the need for a messy content migration. Using an basic, open format like markdown also means there's no content lock-in effect. If you're unhappy with one tool you can easily move to another.

I like the simplicity of Markdown and find the concept of static site generators appealing, so I decided to use Hugo for my new blog. I quickly installed it, created a new site using the included scaffolding tool, added what seemed to be the default theme, and started building my site.

I made some minor tweaks to the theme by adding a small CSS file of my own and customized a few of the theme files to better suit my needs. Then, I began blogging. I had a lot of fun; writing was easy, Markdown suits me well, and I received some positive feedback on Mastodon that encouraged me to keep going.

However, alongside this growing joy of writing, I found myself increasingly dissatisfied with almost every aspect of the site's design, and visiting it just made me disappointed.

Since the writing was so enjoyable, the logical next step was to create my own theme to make sure the output was equally pleasing. Hugo comes with a scaffolding tool for creating new themes as well, but all these structures and tools were starting to get to me. When I saw the large default file structure for a new theme I simply had enough and started looking for a better way of doing things.

Hello Eleventy

There are a whole bunch of different static site generators out there, but I kept seeing recommendations for Eleventy, which sparked my interest, and after reading a bit about it it certainly seemed like a good choice for me as well. It's popular and actively being developed, it's simple and flexible, and it's Node-based. A popular tool increases chances of finding both good information and technical assets like plugins. Its simplicity and flexibility particularly appealed to me after my falling-out with Hugo. Plus, I'm already very comfortable with the Node environment.

Eleventy is perhaps the least opinionated tool I've ever used; it doesn't require any particular file structure, it supports a long list of templating formats out of the box (HTML, Markdown, WebC, JavaScript, Liquid, Nunjucks, Handlebars, Mustache, EJS, Haml and Pug, to be precise), and you can add more if needed. You can even mix and match formats within the same site to suit your needs.

When you create a site with Eleventy, it doesn't come with any pre-installed themes. In fact, themes aren't really part of the Eleventy vocabulary, which feels like a big relief for me. Instead of themes Eleventy has layout templates. They're special templates used to display information from the other templates in the system, and can use any format you like, but a common convention seems to be using Markdown for content and Nunjucks for layout. Layouts can be chained, which means a layout can have a parent layout, for example like this:

posts/post.md:

---
title: My Post
layout: post
---

This is my content.

_includes/post.njk:

---
layout: main
---

<h1>{{ title }}</h1>
<article>
{{ content }}
</article>

_includes/main.njk:

<html>
...
<body>
{{ content }}
</body>
</html>

First the content template post.md points to post.njk and get wrapped in that. That layout template then points to main.njk and the output from the first step becomes the content for the second step, and so on. If you only have one type of content you can of course use a single layout template for that, but it's a very nice way of dividing a page structure into layers. Anyways, the end result of the above example would look like this:

<html>
...
<body>
<h1>My Post</h1>
<article>
<p>This is my content.</p>
</article>
</body>
</html>

The <p> element surrounding the innermost content comes from the built in conversion from Markdown to HTML, but the rest is just a combination of the two layout templates and the content. As you may have noticed there's also a header block surrounded by ---. This is called the front matter, and it's the place to put metadata about the content. You can put any information here, and it will automatically be available to any layouts used etc. This data is also merged "upwards" in the layout chain, so that partial layouts like the ones above can add data to the input from the underlaying template. Very convenient.

New beginnings

So, armed with a new, lightweight technical setup, I moved all my Markdown files over from Hugo and started working on a brand-new version of this site. The default front matter formats differ slightly between Hugo and Eleventy, but that was easily adjusted. Now that I've learned a little bit about Eleventy, I know I could have adapted the front matter parsing (which uses gray-matter under the hood and allows for a lot of customization) to fit the Hugo format instead, but it really wasn't a big deal. The rest of the content was usable, but Hugo's link syntax had to be replaced with regular paths.

I also decided to write my own layouts rather than using a starter project or copy-pasting some "best practice" template. Before I started, I made up some half-conscious principles for the site:

Use modern HTML and CSS, ignore old browsers, let the good times roll!
Use a minimalistic approach, less is more
Use good semantic markup that clearly describes the structure of the content

I wrote a minimal structure for the framework around the content, the "page chrome" if you will, using as descriptive markup as possible:

<!DOCTYPE html>
<html lang="en">
  <head>...</head>
  <body>
    <header>...</header>
    <main>
        <article>
            <h1>Title</h1>
            <p>Content goes here.</p>
        </article>
    </main>
    <footer>...</footer>
  </body>
</html>

It's clean, it's clear, and to my delight there's not a single <div> on the entire site. I don't like divs, and I'm very happy to just use semantic markup and a touch of CSS to style it. Some other things that this site lacks are JavaScript, analytics/tracking, CSS frameworks, responsive design, and custom fonts (actually, I specify sans-serif as font in my CSS and just let go). It wasn't until I realized I wanted a favicon that I added a funny picture of myself to the site, and other than the HTML document itself that's the only file that is loaded (unless you're reading a post that has images of its own, that is). This typically leads to loading times of around 100 ms, which I'm very happy with.

It turns out that when you write clean and descriptive markup like this, you score really high on the Lighthouse tests as a bonus. A few minor tweaks here and there, and I found myself getting a perfect 100/100 score for all four main categories (Performance, Accessibility, Best Practices, and SEO) for both Desktop and Mobile. I'm well aware of the fact that not all websites can be this basic and/or minimalistic, so I'm not too smug about it, but it feels great to get a perfect score like that. The lack of "deliberate" responsive design is also satisfying. Again, with a basic layout like this, everything just works. I added a small padding to the body tag (which also benefits larger screens) and that was it for my mobile adaptation.

I've got the above markup divided into two layout templates: one for posts and one for pages, and one additional main layout that wraps around either type of content. There really isn't anything else to it; just write a few text files and you're good to go.

Tooling

The main Eleventy command npx @11ty/eleventy performs the actual static site generation. It also accepts a --serve argument, which starts a small development server that rebuilds the site and reloads the browser on relevant file changes. I added a few shortcuts to my package.json like this:

...
"scripts": {
    "dev": "npx @11ty/eleventy --serve",
    "build": "npx @11ty/eleventy",
    "clean": "rm -r _site"
},
...

When I sit down to write or work on the site I just run npm run dev and the development server is automatically started. The live reload is very convenient both for tinkering with the site and for writing text. Even though many editors have live preview for Markdown, it's nice to be able to switch over to the actual site and see what your work in progress will look like. I store the entire site in a Git repository both for backup and for deployment.

Publishing

Due to unforseen circumstances with my regular go-to hosting service DigitalOcean App Platform I decided to publish my site on Netlify. They're similar in that they both provide hosting solutions with continuous deployment support. This means you can connect your service of choice to your Git repository, and it will build and deploy a new version of your site for every commit you make to a specific branch. Netlify is a bit more advanced than DigitalOcean in that they can also deploy a private version of your site for essentially any commit or pull request, so that you can preview the result before going live. I've configured it to deploy to a private URL for my main branch, while a separate "production" branch updates the public site.

Configuring the site on Netlify was a breeze. I granted Netlify (limited) access to my blog repository, and it automatically picked up both the build command from my package.json and the default _site output folder used by Eleventy. Sweet. A few seconds later I could access my site online, albeit through a temporary hostname. Once I was happy with the site, I pointed my domain name to Netlify as per their instructions, waited for DNS records to propagate and then for a SSL certificate to be generated, and then it all just worked.

Having a Continuous Deployment service like this ties in really well with my Git-based workflow, and even allows me to push a small change to the live site right from my phone (using Working copy on iOS as my Git client) if I want to.

Joy

Now that this new site is live, I can happily say that it genuinely puts a smile on my face. I sometimes open it on my phone just because it feels good. I'm glad that I took the time to write the entire layout properly from scratch, and I'm pleasantly surprised by how little time it actually took. Eleventy has been fantastic to work with. Despite handling some pretty advanced tasks, it has never felt complicated to me. The Eleventy community seems to be a very friendly and helpful one, and it's been easy to find answers to my questions. I'm eager to give back, and I guess this post is my first small step in doing so. I have another Eleventy-themed post coming, describing some of the customizations I made to have things just the way I like them. It's these small, yet significant, details that ensure the site truly brings me joy.

ATtiny85 Fuses Explained

Martin Gunnarsson — Mon, 20 Nov 2023 18:19:56 +0000

In the world of microcontrollers, a fuse is not only a hardware device that protects circuitry from electrical overload, it's also a concept of low-level configuration settings stored in non-volatile memory. These fuses are typically used to set hardware configuration parameters like clock sources and boot sequences, things that are essential when initializing the microcontroller.

Once set, these fuses remain set until explicitly changed, even if new firmware is flashed into the program memory.

Fuses in the ATtiny85

The ATtiny85 works exactly like this. It has a number of fuses to control essential hardware configuration. The parameters are stored in configuration bits grouped into fuse bytes. Instead of talking about the various bits being "set", the word "programmed" is often used. The reason for this is that a set bit typically refers to a value or 1, while a programmed bit actually has a value of 0. This is slightly unintuitive, but has to do with the fact that the type of memory used is filled with ones when erased, so that the default, "empty" state of a bit is 1. With that out of the way, let's go through the different fuse bytes and their configuration bits.

Low fuse byte

The low fuse byte determines basic settings mostly related to timing. The different bits represent the following parameters:

Bit(s)	Name	Function
0-3	CKSEL	Clock source select. These bits define the clock source to be used by the microcontroller.
4-5	SUT	Startup time. These two bits define the startup time of the microcontroller. A short startup time is great under optimal circumstances, but with a shaky power supply or an external clock source requiring time to stabilize, it might be necessary to take it easy. The exact timing of the startup depends on the clock source selected.
6	CKOUT	Clock out. If programmed, the system clock signal will be output on the CLKO pin, which is PB2 on the ATtiny85. This overrides any other use of that pin.
7	CKDIV8	Clock divide. If programmed, a clock divider will be activated, dividing the speed of the system clock by 8. To read more about the clock speed, please see my post Setting the ATtiny85 clock speed.

High fuse byte

The high fuse byte contains more advanced configuration parameters than the low one. The parameters are:

Bit(s)	Name	Function
0-2	BODLEVEL	Brown-out detection level. These bits control the voltage level threshold for the brown-out reset.
3	EESAVE	If programmed, the EEPROM will remain intact when the chip erase command is run, and only wiping out the Flash (program) memory and lock bits (see Lock bits below).
4	WDTON	Watchdog timer always on. If programmed the watchdog timer will be running at all times. If not programmed, the watchdog timer will be disabled on startup and can be enabled, configured, and disabled by the firmware at runtime.
5	SPIEN	Serial programming and data downloading enable. When programmed, the SPI interface for programming the ATtiny is enabled. Luckily this is the default state. Unprogramming the bit disables SPI, making it impossible to flash new code into the ATtiny.
6	DWEN	Debug wire enable. If programmed, it enables the DebugWIRE interface for debugging, if you're lucky enough to have access to the hardware and software needed to do so.
7	RSTDISBL	External reset disable. If programmed, the external reset functionality is disabled, making the reset pin available for other uses. On an eight-pin microcontroller that normally has five pins available for GPIO, getting an extra one can be very tempting. Before tossing the reset functionality out the window, please note that it's used during SPI programming, which means new code can't be flashed into the ATtiny once this bit is programmed. The only way to make it receptive to new code again is using a high voltage programmer.

Extended fuse byte

In addition to the low and the high fuse bytes there's the extended fuse byte, which only defines a single parameter:

Bit(s)	Name	Function
0	SELFPRGEN	Self-programming enable. When programmed, the flash (program) memory will be writable by the firmware in the ATtiny during operation, offering endless opportunities to shoot yourself in the foot.

Lock bits

The lock bits aren't strictly fuses, but share some similarities. They are used to enable security features in the ATtiny85. There are two lock bits that can represent one of three lock bit protection modes together:

No lock functionality enabled
Disable writing to the program memory and EEPROM in both serial and high-voltage programming modes, and prevent the fuses from being modified.
Like mode 2, but also prevents reading the program memory and EEPROM in both serial and high-voltage programming modes.

Since the lock bits can only be reset using the chip erase command, which also erases the program memory and (depending on the setting of EESAVE, see above) the EEPROM, this effectively protects the code and data in the ATtiny85 from ending up in the wrong hands even if they have access to the chip.

Writing fuses

The fuses related to clock speed (CKSEL and CKDIV8) can be set using the Arduino IDE. Doing so utilizes the avrdude command line tool under the hood, and to set the other fuses you have to use this tool manually.

To calculate the values for the different fuse arguments to avrdude you can use a fuse calculator. They don't just calculate the byte values for you, but also present them as full arguments ready to be passed to avrdude. Here's an example of one such set of arguments, which represents the default ATtiny85 configuration:

-U lfuse:w:0x62:m -U hfuse:w:0xDF:m -U efuse:w:0xFF:m -U lock:w:0xFF:m

The -U command, which is the memory operation specification, is included once for each fuse byte (low, high and extended) and once for the lock byte. The other parts of the argument consists of w for write, the value to be written, and m for immediate mode, which means the value to be written is specified in the argument itself.

The only additional arguments needed are the ones specifying programmer and chip settings. A nice little shortcut is to peek at the exact avrdude command issued by the Arduino IDE. That way you know you're getting programmer parameters and a chip configuration that works. To do this, go into Preferences and enable verbose output for the compile command, then set the clock speed and look for the avrdude command in the rather lengthy output. In my case this looked like this:

"/Users/martin/Library/Arduino15/packages/arduino/tools/avrdude/6.3.0-arduino17/bin/avrdude" "-C/Users/martin/Library/Arduino15/packages/arduino/tools/avrdude/6.3.0-arduino17/etc/avrdude.conf" -v -v -v -v -pattiny85 -cusbtiny 
CMD: \[50 08 00 00] \[00 50 08 ff]

We can now combine the relevant parts from the two sources into a full command that does what we want:

"[...]/avrdude" "-C[...]/avrdude.conf" -v -pattiny85 -cusbtiny -U lfuse:w:0x62:m -U hfuse:w:0xDF:m -U efuse:w:0xFF:m -U lock:w:0xFF:m

Run it, and hopefully you're good to go.

Reading fuses

If you just want to check the configuration of an ATtiny you can remove all the write instructions from the command above and run something like this:

[...]/avrdude -C[...]/avrdude.conf" -pattiny85 -cusbtiny

Which will spit out a nice little overview:

avrdude: AVR device initialized and ready to accept instructions

Reading | ################################################## | 100% 0.00s

avrdude: Device signature = 0x1e930b (probably t85)

avrdude: safemode: Fuses OK (E:FF, H:DF, L:62)

avrdude done.  Thank you.

Here you see both the device signature as well as the values for the low, high and extended fuse bytes.

Getting out of trouble

As mentioned repeatedly above, some fuse settings puts the ATtiny85 in a state where it can't be re-programmed and/or reached again without a high-voltage programmer. This is sort of a back door built into the ATtiny, whereby applying 12V to the reset pin with precise timing and then sending serial commands through a few other pins chips can be brought back from the dead. I'll write more about it in the future, but for now I'll refer to this excellent blog post by Eric Draken.

Happy tinkering!

Setting the ATtiny85 Clock Speed

Martin Gunnarsson — Sat, 11 Nov 2023 17:26:15 +0000

Background

The clock speed of the ATtiny85 can be set using one of several internal clock sources, or an external one (like a crystal oscillator) for full flexibility.

The default setting utilizes the internal 8 MHz oscillator combined with a clock divider of 8, resulting in a 1 MHz clock speed. This clock divider can be disabled to run at the native 8 MHz. Additionally, there's another clock source called the Phase-Locked Loop (PLL), which doubles the internal frequency to achieve a 16 MHz clock speed.

When getting started with the ATtiny85 the most common choices are running the internal clock source at either 1 or 8 MHz. Selecting the appropriate clock speed is very important, especially for time-sensitive code, and some libraries require a specific speed to function correctly.

Once you've moved into more complex projects, there are also ways of adjusting the clock speed at run-time using code, but that's a story for another day.

Setting the speed

To set the clock speed of the ATtiny in the Arduino IDE, first ensure you have installed a suitable board definition for ATtiny support. You also need access to an Arduino or a dedicated programmer for flashing it.

Begin by selecting the correct board in the Tools > Board menu. Then look in the Tools > Clock menu and select Internal 1, 8, or 16 MHz. Do not select an external clock source unless you have one properly set up, as it could make flashing the chip again impossible without the use of a high voltage programmer.

After selecting the correct board and clock speed, ensure the appropriate programmer is chosen in the Tools > Programmer menu. Connect the ATtiny to the programmer and select Burn Bootloader from the Tools menu. The operation only takes a second, then you should be good to go.

Under the hood

Despite its name, the Burn Bootloader command actually doesn't burn a bootloader into the ATtiny; it just changes the value of certain fuses to match the chosen clock configuration. Fuses are a common way of storing essential configuration parameters in microcontrollers. They are typically stored in non-volitile memory and remains set even if new content is flashed into the program memory. I've written an introduction to ATtiny85 fuses that explains this in more detail, as well as listing all the different configuration bits that can be set.

Happy tinkering!

Serial debugging on the ATtiny85

Martin Gunnarsson — Fri, 03 Nov 2023 08:46:12 +0000

Background

The ATtiny85 is part of the ATtiny family of microcontrollers, originally from Atmel, now Microchip Technology. It is very small, with only eight pins, six of which are available for I/O. Despite its limitations, it's surprisingly accessible to beginners (myself included) thanks to its compatibility with the Arduino IDE.

The ATtiny85 lacks many features that make "real" Arduinos so easy to work with for hobbyists, such as a proper serial port that makes it easy to send debug messages to a computer. Since most people don't have access to specialized debugging hardware and software, many tinkerers resort to turning LEDs on and off in order to indicate various states of a program. I usually develop the code on an Arduino, where debugging is slightly more straightforward, until I'm happy with it and then transfer it to the ATtiny85. This approach works quite well up to a certain point, but sometimes you simply need to understand what's going on inside the ATtiny85 itself.

Serial communication

As mentioned, the ATtiny85 doesn't have a hardware serial port, and even if it did those pins would probably get used for other things most of the time. Luckily there are other options. For one of my hobby projects I really wanted to know what value I was receiving from an external chip, and decided to give ATtinySerialOut a go. It's a super compact "software serial" library written by Armin Joachimsmeyer specifically for ATtiny microcontrollers.

The library can be installed through the Library manager within the Arduino IDE by simply searching for its name and clicking Install.

A very basic example

Here's a short snippet to get started with ATtinySerialOut. The default output pin is PB2 on ATtiny85.

#include <ATtinySerialOut.hpp>

void setup() {
   initTXPin();
}

void loop() {
    Serial.println("Hello world!");
    delay(1000);
}

Actually, the above code didn't work for me, since the ATtiny core I'm using in the Arduino IDE doesn't define pin constants like PB2. If you run into the same problem, or want to specify a different pin, you can define the TX_PIN macro before including the library, like this:

// The pin must be defined before the library is included
#define TX_PIN 2
#include <ATtinySerialOut.hpp>

void setup() {
   initTXPin();
}

void loop() {
    Serial.println("Hello world!");
    delay(1000);
}

The library implements a whole bunch of nice methods for sending various kinds of data, very convenient.

Speed

The default baud rate of ATtinySerialOut is 115200. In order to change that, a special macro can be defined:

// The macros must be defined before the library is included
#define TINY_SERIAL_DO_NOT_USE_115200BAUD
#define TX_PIN 2
#include <ATtinySerialOut.hpp>

void setup() {
    initTXPin();
}

void loop() {
    Serial.println("Hello world!");
    delay(1000);
}

Using the above macro, the baud rate now depends on the clock frequency of the ATtiny. For 1 MHz it's 38400 and for 8/16 MHz it's 230400. You can change the clock frequency in the Tools menu of the Arduino IDE and write it to the ATtiny using the Burn bootloader option in the same menu. There are some caveats to this, for more details please see my post Setting the ATtiny85 clock speed.

Proxying

Great, we can now transmit data using just a single pin, but where to receive it? In my case, I just wanted to read the value in plain text, so I decided to receive it on a regular Arduino and re-transmit it to my laptop over USB, so that the Arduino acts like a small proxy between the ATtiny and the laptop. Using a serial to USB-adapter I guess it would be possible to receive the data right into the computer, but in my case I just wanted to get on with trying to solve the real problem I was stuck on.

Here's the code for the Arduino serial proxy using the built in SoftwareSerial library.

#include <SoftwareSerial.h>

int rxPin = 10;
int txPin = 11; // This can be any other free pin if you don't need to send data back to ATtiny

// Set up a new SoftwareSerial port
SoftwareSerial softSerial(rxPin, txPin);

void setup() {
    // This is the serial interface between the Arduino and the laptop
    Serial.begin(57600);
    Serial.println("Ready");

    // This is the serial interface between the Arduino and the ATtiny
    softSerial.begin(38400);
}

void loop() {
  if (softSerial.available() > 0) {
    char received = softSerial.read();
    Serial.print(received);
  }
}

As you can see I've set the SoftwareSerial port to 38000 bps, which was needed in order to achieve reliable data transfer. Remember that whatever is receivng the transmission must share ground with the transmitting ATtiny

Summary

If you just want to get this all working, here's what you have to do:

Install the ATtinySerialOut library from within the Arduino IDE.
Set the clock frequency of your ATtiny to 1 MHz.
Flash the following code snippet to your ATtiny:

#define TINY_SERIAL_DO_NOT_USE_115200BAUD
#define TX_PIN 2
#include <ATtinySerialOut.hpp>

void setup() {
    initTXPin();
}

void loop() {
    Serial.println("Hello world!");
    delay(1000);
}

Flash the simple proxy code above to your Arduino.
Connect your Arduino to your laptop and power up your ATtiny.
Once they're both running, connect pin 2 from the ATtiny to pin 10 on the Arduino, and make sure the two circuits share a common ground.
Open the Serial monitor in the Arduino IDE and watch the messages come rolling in.

Happy tinkering!