Intro

I've had various websites over the years, made with various different tools, from handcrafted html, to the C preprocessor (yep, using GCC to generate html!), to server side includes, to wordpress. I wanted to make a website to write about some of my making projects, I didn't want it to also become a programming project, and also wanted to move away from the rather heavy platform that wordpress is for such a small website. In recent years static site generators (SSG) have become quite popular as a way of running a website, so I thought I'd give one of those a go.

What I didn't realise was the rabbit hole I was about to jump head first into, and as it turns out, how hard it is for modern website platforms to do simple things with images. Having finally conquered this, many people asked me to write about the experience, and what my eventual solution was. That's this article.

The problem

What I'm looking for in a website platform, be it a SSG, or some sort of dynamic platform, is simplicity. The novelty of coding websites from scratch wore off long ago, and I just wanted something that would handle most of it for me. The main sticking point however, is around images. Specifically what I am looking for with image handling for a website platform is this:

Say I have a photo, let's call it img_0001.jpg. It's 4896x3264 pixels in size, straight out the camera.

If the sytem has a webinterface, I expect to hit upload, the image uploads into the website, and website platform does all the resizing stuff.

If its a static site generator, I expect I include a path in the markdown something like ![a photo](images/img_0001.jpg). And then when I generate the site, it does all the resizing.

What do I mean by resizing? well the image is too big, it's antisocial to throw many megabyte images at people on your website. I want it to take that image and make say 1600px wide, 800px, 480px wide files that can then be served. Then I expect the site generator, or site platform to create an element with a srcset entry for each of the images.

That's it. That's all I want the SSG or website platform to do. Responsive images, with auto resizing.

Unfortunately, it turns out this is no where near as simple as it may first appear.

The options

I asked on mastodon for recommendations for SSGs and platforms to try. Ths list below is what came most recommended.

• Hugo
• Eleventy
• Jekyll
• Mkdocs
• WriteFreely
• Ghost
• Pelican

Hugo

Hugo was the first one I tried. It's got a pretty good quick start guide, and within about 15 mins I had a basic website running locally on my laptop. Great. I added an image. It filled the screen. Oookay, this isn't as simple as I hoped. I started googling for how to do it. I found a well writen guide by Laura Kalbag. It all looked so close. First one on the list and I'd have a website up and running.

Hah, so naive.

I just could not make any sense of how to make it work. I eventually posted on The hugo forum, hoping that I had just missed something obvious.

I was genuinely surprised by the replies.

Before you start with such things you will have to get the basic understanding of how the peces can be put together.

   markdown for content
   layouts for the HTML skeleton
   partials are like functions for templates
   shortcodes like functions for markdown
   …
   at that stage its coding/programming not text editing

The docs are quite technical and not tutorials but if you spend some time…

start here: Content management | Hugo (at least the first four chapters
and read about Templates | Hugo (at least up to chapter seven.

Yep, to add a photo to my website, I'm expected to read seven chapters of the website documentation, to be able to create a simple website with responsive images. What really urked me was the end of the post.

The bottom line is, if you are unwilling to invest the time required to learn these things, then Hugo is not for you.

Clearly Hugo is not for me.

Someone else added:

Hugo is not for the faint of heart, and I like they acknowledge that in requesting help write-up. I spent 80-100 hours setting up my first website, but the second took less than 24 hours.

This website is not my job, it's a simple blog about the things I make. I don't want to sacrifice two weeks of fulltime work to just add an image to my blog. If I was a professional webdeveloper who needs hugo for work, maybe it's worth the time. But for my usecase, life's too short.

I moved on.

Eleventy

Eleventy was the next for me to try. Here I think part of my problem with eleventy was just bad timing. A new major version of eleventy had just come out. None of the documentation had been updated for the new version. I just couldn't get a website to work. Let alone try and get responsive images working. Not that I could find a lot of documentation about responsive images.

Wordpress

At this point I was so fed up with SSGs and shit documentation I started looking at just using wordpress again. But I was put off by the Wordpress and Wordpress Engine dispute, I didn't want to support such a platform. Then when they publically embraced the new US regime. That was the final nail. Nope. Don't want to use wordpress.

Jekyll

Next up was Jekyll. I just could not find enough documentation on how to do responsive images. It did at least have basic images in the docs in a realtively easy to find way. But not responsive images.

Mkdocs

Mkdocs came recommended by a few people. But it's not really a blog type platform it's more for documentation for a project. It also doesn't handle responsive images.

WriteFreely

WriteFreely was recommended by a couple of people on mastodon. But it doesn't support responsive images.

Ghost

Ghost was recommended by a few people. I initially discounted it because it's a paid platform and not self hosted. An unintentional case of Cunninghams Law got me the documentation for how to self host Ghost. So I gave it a go. Within half an hour I had a website running on my raspberry pi. I started to write a post on the built in editor. I couldn't find a way to upload images. No matter what I tried. You're supposed to just type ![]() and it opens a box so you can upload your image. But nope. Didn't work. On a hunch I switched from firefox to chrome. Here, the editor did pop open the dialogue box, I gave it an image to upload. It claimed success. There's even a resized image on the disc. And it didn't work. I just couldn't make it do what it claimed. The whole thing devotes more screen space and UI functionality to subscription management and sign ups. I'm not sure what the usecase ghost is trying to use, but I just couldn't get it do a basic image, let alone a responsive one, and it wasn't fun trying.

Ghost also has the problem that it's an absolute shite to search for. Ghost as a word just gives too many search results that aren't related to the ghost website platform. It's almost as bad as ikea's Not light when it comes to googling it.

Pelican

So pelican was one I tried. Then gave up on. I couldn't get responsive images to work. I could see the building blocks that are supposed to make it work. There's a simple plugin that does it all for you, you just need to install it and configure it. What let this down was the documentation. The Readme.md is detailed, it tells you all the code snippets you need to make it work. If you're an experienced pelican user, I'm sure that makes perfect sense. But if you're new. If you just want a simple website with responsive images, you end up sat on the sofa on valentines day screaming at a github page "YES BUT WHERE THE FUCK DO I PUT IT??!".

At this point I ranted on mastodon.

And the wonder that is the fediverse did it's thing. A user called @fm2279@social.coop stepped forward to help me make it work. They told me where I needed to put the code from the github page to make evertyhing work.

Responsive images in Pelican

So. Just in case someone else is out there trying to make responsive images work in pelican and can't work out what to do. I put the following python code in the pelicanconf.py file. I stuck it at the end of the file.

IMAGE_PROCESS = {
    "crisp": {
        "type": "responsive-image",
        "srcset": [
            ("1x", ["scale_in 800 600 True"]),
            ("2x", ["scale_in 1600 1200 True"]),
            ("4x", ["scale_in 3200 2400 True"]),
        ],
        "default": "1x",
    },
    "large-photo": {
        "type": "responsive-image",
        "sizes": (
            "(min-width: 1200px) 800px, "
            "(min-width: 992px) 650px, "
            "(min-width: 768px) 718px, "
            "100vw"
        ),
        "srcset": [
            ("600w", ["scale_in 600 450 True"]),
            ("800w", ["scale_in 800 600 True"]),
            ("1600w", ["scale_in 1600 1200 True"]),
        ],
        "default": "800w",
    },
}

It's a direct copy from the github page. The thing that was missing. Was the info on which file I had to put it in. That's it. One, maybe two sentences missing from the documentation.

I then put the following markdown code in a post.

![A woodworking marking gauge made of wood (ash - fraxinus excelsior), brass, and polished steel. It sits on a wooden workbench.](/images/MarkingGauge/IMG_20241123_210200.jpg){: .image-process-large-photo}

And the result is a responsive image.

It works! I have a simple staticaly generated site with responsive images. It does all the resizing stuff for me. It's what I wanted.

Conclusion

Almost every system I tried, like many opensource projects, is severely let down by it's documentation. And in some cases by the unwelcoming attitude of the developer community that supports the project. I don't think I have any unreasonable expectations with what I am trying to do. It's 2025. Responsive images should be the norm. It's basic accessibility (along with alt text). It should not require 2+ weeks of fulltime labour to make a simple website with such a basic accessibility feature.

Perhaps if the SSGs spent less time worrying about being the fastest, and instead spent a little more time focusing on making the most accessible websites, this would have been a simpler endeavour.