Eleventy

Added by to Tools on and tagged · Node.js · Eleventy ·

About 5 minutes to read (887 words)

Cake Batter Garden Mandala
Eleventy
Eleventy
(see original image in new window)

Spring has sprung, and with it comes thoughts of new tools to build a Web site. Okay no the picture has nothing to do with Web sites but isn't it pretty?

I use Hugo to build this site, and have for a while now. Hugo builds fast, includes loads of features, and by now has the added benefit of being familiar. It's still fun to see what else people use for their sites, though.

Eleventy caught my eye with its claims at being a simpler static site generator. Node.js powers Eleventy. That caught my attention because of how much I've been using the platform at work recently.

Aided by the core documentation, I'll make a single page site with a stylesheet. To my mind, that's the "Hello World" of static site generators. It covers the three core elements: content, layouts, and including files outside of the content/layout flow (stylesheets, images, etc).

Starting fresh with package.json

I'll follow the suggestion from docs and install Eleventy locally to the site project.

$ mkdir rgb-eleventy
$ cd rgb-eleventy
$ npm init
$ npm install --save-dev @11ty/eleventy
$ npx eleventy
Processed 0 files in 0.03 seconds

Yay, the process works! Now I need content.

Content: Read Markdown, write HTML

I can stick with familiar Markdown content, since Eleventy supports it through markdown-it. Throw a couple sentences in index.md:

# Random Geekery Blog

But in [Eleventy][].

[Eleventy]: https://www.11ty.io/

And rebuild the site.

$ npx eleventy
Writing _site/index.html from ./index.md.
Processed 1 file in 0.07 seconds

So what's in _site/index.html?

<h1>Random Geekery Blog</h1>
<p>But in <a href="https://www.11ty.io/">Eleventy</a>.</p>

That's HTML, all right. But I need a full HTML page. Rather than make my content file more complex, I'll use a layout template.

Templates

Eleventy layouts are similar to layouts in other site generators. They provide a skeletal HTML file along with special directives. These files get combined with your content files, creating complete pages that have a consistent layout and design.

Rather than focus on all the templating languages Eleventy supports, I'll use Nunjucks. I don't want to spend time looking at all the templating languages supported by Eleventy. I'll just use Nunjucks since it appears frequently in the docs.

My _includes/layout.njk is pretty much your basic minimal HTML 5 skeleton.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{title}}</title>
  </head>
  <body>
    <h1>{{title}}</h1>

    {{ content | safe }}
  </body>
</html>

content comes from the body of the content file, while title is in index.md's front matter. That's also where I specify layout.

So yeah. I should probably add some front matter.

---
layout: layout.njk
title: Random Geekery Blog
---

But in [Eleventy][].

[Eleventy]: https://www.11ty.io/

Rebuild, and now _site/index.html looks like a Web page.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Random Geekery Blog</title>
  </head>
  <body>
    <h1>Random Geekery Blog</h1>

    <p>But in <a href="https://www.11ty.io/">Eleventy</a>.</p>

  </body>
</html>

Use Pass-through File Copy for static content

Finally, I want to put in some CSS. I could just insert it in the template, but I prefer to keep styles in their own file.

Eleventy's default behavior is minimal. It knows content. It knows templates. Going beyond that requires special instructions. In order to add static content like stylesheets, we must configure Eleventy to recognize them.

My .eleventy.js tells Eleventy that everything in the folder static/css gets copied into site output unmodified.

module.exports = function(eleventyConfig) {
    eleventyConfig.addPassthroughCopy("static/css");

    return {
        passthroughFileCopy: true
    };
}

I don't have any specific styles in mind. I'll browse through a listing of sufficiently contrasting color pairs demonstrated by the accessibleColors Mastodon bot until I find one that I like.

River Bed and Green Mist for accessible color contrast
River Bed and Green Mist for accessible color contrast

static/css/site.css doesn't contain much.

body {
    background-color: #ced3b6;
    color: #435866;
}

Now the layout must include a link to my new stylesheet, of course.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{title}}</title>
    <link rel="stylesheet" type="text/css" href="/static/css/site.css">
  </head>
  <body>
    <h1>{{title}}</h1>

    {{ content | safe }}
  </body>
</html>

Using the local server

It's easier for me to see my styles than to imagine them, so let's load the Eleventy development server via the command line.

$ npx eleventy --serve
Writing _site/index.html from ./index.md.
Processed 1 file in 0.13 seconds
Watching…
[Browsersync] Access URLs:
 ----------------------------------
       Local: http://localhost:8080
    External: http://10.0.0.26:8080
 ----------------------------------
          UI: http://localhost:3001
 UI External: http://localhost:3001
 ----------------------------------
[Browsersync] Serving files from: _site

UI? The what now? Let's look at that first.

screenshot of Eleventy UI admin panel
screenshot of Eleventy UI admin panel
(see original image in new window)

Neat. Not strictly useful for something this small, but good to know it's there. Anyways.

screenshot of my single page Eleventy site
screenshot of my single page Eleventy site
(see original image in new window)

Yay, it worked!

Good enough

I've learned about how Eleventy handles content and layouts, along with configuration details like pass-through copying for stylesheets. I haven't learned about deployment, partly because I have no intention of publishing this page anywhere. I haven't learned about blogging with Eleventy, but I might someday. At least I won't have that blank stare when folks bring it up.