Nearly ten years after my last blog post, I've updated my website, and accordingly, here is a hello world post from Eleventy!

Elle, the Eleventy mascot

A bit of background

For a period of about 5 years, I used Octopress, which was a blogging framework on top of Jekyll. Jekyll, if you don't know, is a static site generator built by Tom Preston-Werner, co-founder of Github. If you've ever written something for Github Pages, you've used Jekyll 😄. As a framework/theme on top of Jekyll, Octopress worked pretty well! It had a nice choice of typography and layout, handled mobile sizing well, and even had some nice touches like dropquotes and plugins. I was also writing a fair amount of Ruby and raw HTML code at the time (not so much Javascript), so a blogging engine built upon Ruby suited me fine. I hand-rolled some deployment scripts to deploy to Amazon S3, pointed my domain host name server to S3 and got a static website.

Towards the start of 2015, Brandon Mathis announced that Octopress would be moving to Octopress 3.0. It was both a big restructure in terms of framework, and ... under-explained. There was a blogpost on the website, a bunch of commits to the Github repo, and that was kind of it. I also changed jobs, and then, countries, and really didn't feel up to re-writing my whole website to cope with an huge change (having lived through the Angular 1 to Angular 2 schemozzle).

So I hacked together a frontpage in raw HTML, plonked it down in front of Octopress (yes, that's the technical term for it), and went back to work.

My hand-rolled HTML frontpage.

So why Eleventy?

Eleventy is a neat static site generator written in Javascript. Static sites are simpler and faster. I probably could have reverted from Octopress back to Jekyll, but I've become a lot more familiar with Javascript frameworks than Ruby in the last few years on my holiday. I did spike out a version of my website in Hugo, which is built in Go. It is incredibly fast, but I'm just not as familiar with Go as I am with Javascript. So I was looking for an SSG build in Javascript, and really the options there are basically Astro or Eleventy. Astro is very popular but seems better suited to building huge enterprise websites, and I'm not really interested in how well Astro improves your conversion rate. Eleventy fits my needs, is simple to get up and running with, and feels much closer to the cozy web that I think best suits personal blogs.

Didn't you just replace one framework with another?

Yep! And that's not ideal. But fundamentally, I still need something that processes the Markdown files into HTML. So the options are either pre-processing them with some sort of shell script or using a static site generator. And frankly, it's a lot easier using a static site generator. That's what they're built to do.

For the moment, I've chosen to go with Eleventy-Duo as a template for this site. I've pretty heavily customised it for my needs. It's given me a pretty useful base for being able to port my old posts over to Eleventy, and it allowed me to proofread the old content and see how it rendered. Given that Jekyll and Eleventy both use Liquid syntax for templating, a lot of pages just worked but there was still a number of custom Octopress-only liquid tags in use, and I had also made a few custom liquid templates that needed correcting or replacing. Wherever possible, I've tried to revert pages back to pure Markdown for some future proofing.

What's not working?

Images are hard

Well, Eleventy Duo is still built upon Eleventy 2.0.1, which uses an old version of the Image plugin. It works on the idea of processing the raw HTML coming out of Eleventy, reading the <img> tags, and modifying the images therein at build time, doing the heavy lifting of generating different sizes for you, fetching remote hosted images and storing them locally, etc. You still need to write your own CSS to handle media-width queries and so forth. It's great if you are building from the ground up and are managing the eleventy data pipeline well.

I am not building from the ground-up 🤷, and I'm more focused on getting up and running. My ideal world is that I can call an image in Markdown with a size, and it displays.

![Image alt text|500](/images/some-image.jpg)

I'd love this to generate a scaled down version of the image at 500 pixels wide.

Strictly speaking, you should be able to export a new addShortcode call into the eleventyConfig module of .eleventy.js, but you still end up with a non-Markdown Liquid/Nunjucks shortcode in the middle of your text, as an example from the 2.0.1 docs shows (note that the below example has extra spacing to stop Eleventy attempting to process it as a shortcode 😆):

{ % image "./src/images/cat.jpg", "photo of my cat", "(min-width: 30em) 50vw, 100vw" %}

with the corresponding .eleventy.js example code being:

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

module.exports = function(eleventyConfig) {
    eleventyConfig.addShortcode("image", async function(src, alt, sizes) {
        let metadata = await Image(src, {
            widths: [300, 600],
            formats: ["avif", "jpeg"]
        });
        let imageAttributes = {
            alt,
            sizes,
            loading: "lazy",
            decoding: "async",
        };
        return Image.generateHTML(metadata, imageAttributes);
    });
};

Currently, I'm manually resizing images prior to adding them to posts, but ideally, the data pipeline would transform my images to the size that I request in my Markdown tag. But I'd rather have something than nothing, so manual conversion wins for the moment.

Step 1 of ... many?

Having got this up and running, I'm actually also writing a new version in Eleventy. Because nothing says finished like a complete rewrite, huh? Whilst Eleventy-Duo is fantastic for a simple, content-forward blog template, I'd actually like to spend some time better understanding Eleventy's data pipeline and collections, and leveraging those to better translate some of my ideas to the web. Stay tuned for more!