Tool Spotlight: Eleventy

I absolutely love how many cool tools there are out there! The other day, while trying to figure out the new website for the Race Against Time, I came across Eleventy. In a nutshell, its a JavaScript static site generator like Gatsby (which powers this website).

Given how many static site genenators there are out there, you might ask, why do we need another one? 😅

I don’t have an answer to that, but I can tell you about why it made sense for rebuilding the Race Against Time’s website, and compare it to my experiences building this blog.

Starting a Site… Again

As mentioned when I started this blog, I’ve tried a lot of different tools for hosting what is essentially a basic website. In those cases, and for the Race Against Time, there’s only a small list of idealized requirements:

• Routine things should be easy: Since 99% of the site is writing text and adding images, there should be little complexity for that.
• Low maintenance: I don’t want the site to be ‘down’ or require constant updates. Again, the end product is mostly simple HTML.
• Simple, not necessarily easy: I’d rather have a tool that is simple than one that hide complexity. More on that soon.
• Data transformations: For the Race Against Time, a lot of want I want to present—like prizes, achievements, or guests—is just data that is iterated over, and rendered.

And an optional requirement: it would be nice if non-programmers could work on it. This wasn’t super high priority as I expect that it’ll mostly still be just me working on the project.

Given those requirements, what did I end up looking at?

Wordpress

Wordpress checks a lot of boxes. It’s really easy to update content, themes, and so on, has tons of existing templates and plugins, and is easy for non-programmers. It isn’t free (though, it is inexpensive), and doesn’t require a ton of maintenance… but generally hasn’t been my favourite.

I couldn’t find a way to transform data (like JSON) into rendered blocks, but I’m sure something like that exists somewhere in Wordpress-land.

Gatsby

As I said, I use this for the blog, and generally I’ve been happy with it. 99% of what I need can be written as markdown files, and the site itself would require no maintenance (since it’s a static site). Not entirely non-programmer friendly, and can definitely support data transformations.

…But it’s a lot of code for such a small project, with a lot of abstractions that probably aren’t needed?

Enter Eleventy

I’m not going to claim that 11ty is the perfect tool, but I think it works really well for what amounts to a single-page (or small number of pages) website.

This is the quick start guide:

npm install -g @11ty/eleventy
echo '# Page header' > README.md
eleventy

…Which will generate an HTML file from a markdown file. That’s it.

And while that seems stupidly un-useful (spoiler alert: it is), it’s that simplicity that makes it shine.

In a more realistic example, the Race Against Time’s website is generated from a markdown file that looks like this:

---
title: The Race Against Time
layout: homepage.liquid
---

# The Race Against Time VII {#overview}

{% floatImg "images/crono.png" "right" %}

{% comment %} The rest of the content is beyond here. {% endcomment %}

Eleventy can use that front matter to define variables that are used in template files, define what templates to use to render the page, define the rendering engine (I’m using liquid but many others are supported). Heck, I’ve even defined my own tag here, floatImg, to render an image in a particular way. The code for that is defined in .eleventy.js:

module.exports = (eleventyConfig) => {
  eleventyConfig.addShortcode("floatImg", floatImg);
  // ... other configuration ...
};

const floatImg = (path, styles = "left") => {
  return `<img src="${path}"
    class="float-image ${styles}"
    style="shape-outside: url('${path}')" />`;
}

With these tools, it means I can set up all my layout and other core functionality and just focus on writing simple markdown documents!

I know that markdown + a layout engine like liquid is probably possible in other ways, but 11ty’s focus on data also means that I do things like define a JSON file and generate pages or even fetch data asynchronously at build time.

I didn’t even mention that it can handle hot-reloading which is a fantastic developer experience.

As I keep learning about new plugins and aspects of 11ty, it just seems like a neat, lightweight tool to tackle static website generation!

If nothing else, it’s been fun to work with and learn 💗

I’m hoping to publish the source code of the website publically soon, even though there isn’t much to it, just to show what it’s like.

Anyway! I hope that was helpful. I’ll definitely get back to talking about NodeCG, but as the Race Against Time draws closer, I find myself juggling projects a lot 😅