Making a simple Eleventy blog template

If you’ve worked with TypeScript, React or Next odds are you’ve encountered an update that broke a number of features on your page. When that happens you’re left wondering if there’s some simpler or older technology you could use that would just be less hassle. Well at least that’s what we were talking about at the office after the last Next update with translations.

Back to the past

Thinking about simplicity the things that come to mind are languages like css, html or even markdown. Simple is one thing and stability is another, there's zero chance we’ll get a groundbreaking markdown update next year, which will break our projects. That’s why we looked at some frameworks that could work with something as simple as that, going in the complete opposite from our usual TS, Next & React stack. That’s how I stumbled upon Eleventy, a versatile SSG which works with a number of file formats - among them Markdown which is exactly what we were looking for and as simple as it gets.

11ty performance

Setting up a simple blog page

So the next question was could we actually create a page using only simple languages like markdown? The answer is Eleventy and it's really simple to use just like we wanted. Obviously you’ll need to npm install the run it and since we’re already on a blog page let's use that for our example.

First we’ll need a index.html page from which we will be able to access our content and a posts folder for our blogposts in markdown. We can add an example post in markdown and run localhost to see eleventy will automatically render it to html (neat and simple just like we wanted)

├── posts
│   ├── my-first-post.md
│   ├── my-second-post.md
├── index.html

We'll also need to do some layout for our blog, this is by default kept in a _includes folder, but it's easy to rename it in the settings if you want to call it layouts or whatever.

├── posts
│   ├── my-first-post.md
│   ├── my-second-post.md
├── _includes
│   ├── layout.html
├── index.html

To use the layout for our index page we need to include it in a front matter section at the top of the page like this:

---
layout: layout.html
---
the content of our page

We also need to tell the layout file where the content will go and for that we use double curly braces, reminiscent of liquid or nunjucks (more on that later btw.)

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Our blog</title>
  </head>
  <body>
    <h1>Welcome to our blog</h1>
    <div>{{ content }}</div>
  </body>
</html>

Obviously our blogposts will also need a layout and Eleventy has a neat trick to do it for all of them with just one line. We simply need to go to our posts folder, create a json file with the matching name (ie. posts.json) and point it to our layout file.

{ 'layout': 'layout.html' }

Front Matter

The fact we're using a json file to import the layout into our blog pages doesn't mean we can't also use front matter there. For example we'll definitely want to use different titles for our posts so we need to add them to the front matter:

---
title: the title of our post
cover: /images/FirstPostCover.png
---

and then import them in the layout

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>{{ title | default: "Our blog"}}</title>
  </head>
  <body>
    <img src={{ cover | default: "/images/default.png"}} alt={{ title | default:
    "Our blog"}} />
    <h1>{{ title | default: "Welcome to our blog"}}</h1>
    <div>{{ content }}</div>
  </body>
</html>

This is best suited for simple SEO tags like titles, meta descriptions, open graph tags etc. which we can now make sure will use dynamic titles, descriptions or images that we will specify in the front matter. For other things we can use something called collections.

Collections

Collections let us iterate over a group of files, like our posts. To do so we need to set a tag in that same json file we created and set a tag for them:

{
    "layout": "layout.html"
    "tags": "post"
}

Now we can for example list our blogposts on our index page. To do so we need to iterate over the post collection in the data:

---
layout: layout.html
---
{% for post in collections.post %}
<h2>{{ post.data.title }}</h2>
{% endfor %}

If the syntax looks weird to you it's Liquid - or Nunjucks here specifically, a simple templating language used for static site generators. If you don't like it you can also achieve the same result using JavaScript as Eleventy does support that as well but it would kinda defeat the whole purpose of going away from React.

Static Site Generator

That said with these few simple steps we can get our blog page running in no time at all, which is exactly what we were looking for - quick and easy! I should say it's hardly a surprise that a static site generator works well for generating a pretty straightforward static site. I might've painted a too rosy a picture with this simple overview so I promise I'll go over some of the downsides of Eleventy in part 2 (where we'll get into components!)