Itsiest, Bitsiest Eleventy Tutorial

Want to get started with Eleventy but feel overwhelmed? Try out this pared-down tutorial

by Sia Karamalegos

News reporter holding a microphone up to a possum with its mouth open as if speaking
Photo from @PossumEveryHour

I like to talk and write about Eleventy a LOT. I always run into this problem of having to introduce Eleventy to people not familiar with it in a short way. So, I wrote up this miniature demo to give people a flavor of Eleventy without overwhelming them with all the details. If you like it as much as I do, maybe it will inspire you to learn more!

The code for this repo can be found on Github. This article is meant for people new to Eleventy and will show you how to:

  1. Start up the most minimal Eleventy project with one page (the main branch)
  2. Add a layout and styles (the 2-layout-styles branch)
  3. Add a blog and a list of all blog posts (the 3-blog branch)

To get started, clone the repo, cd into it, and run npm install.

Taking a step back #

The steps to get it to this point ("step 1") were:

  1. Make a new directory
  2. cd into it
  3. npm init -y
  4. Install Eleventy with npm install @11ty/eleventy
  5. Edit the package.json to add a start script of npx @11ty/eleventy --serve and a build script of npx @11ty/eleventy.
  6. Create index.md
  7. Run the start script. Eleventy processes index.md into the default output folder /_site/ with the filename index.html.

Step 2: Add a layout and styles #

Checkout branch 2-layout-styles to see this next step. In this step, I move our source code to a /src/ folder, add a layout file, and add a CSS styles file.

To build it on your own:

First, we move our source code to /src/:

  1. Create /src/ and move index.md into it.
  2. Create a .eleventy.js file in the root of the project with the following content:
module.exports = function(eleventyConfig) {
  // Set custom directories for input, output, includes, and data
  return {
    dir: {
      input: "src",
      includes: "_includes",
      data: "_data",
      output: "_site"
    }
  };
};

Most of those are defaults - change their name in this file if you'd like to use a different name. You'll need to restart your dev server for any changes in this file to take effect.

Next, add a layout:

  1. Create /src/_includes/layout.njk. This is a Nunjucks template, but you can use many others. The stuff in curly brackets are things that we will fill in at build time:
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <!-- Grab title from the page data and dump it here -->
  <title>{{ title }}</title>
</head>
<body>
  <!-- Grab the content from the page data, dump it here, and mark it as safe -->
  <!-- Safe docs: https://mozilla.github.io/nunjucks/templating.html#safe -->
  {{ content | safe }}
</body>
</html>
  1. Add YAML frontmatter to the top of our /src/index.md file to tell it which layout to use and to set the title data attribute:
---
layout: layout.njk
title: The Best Eleventy Demo TM
---

Finally, add some CSS:

  1. Create /src/style.css. Add some CSS to that file.
  2. Add <link rel="stylesheet" href="/style.css"> to the head of /src/_includes/layout.njk.
  3. Now we need to tell Eleventy to "pass through" any CSS files. We do this in .eleventy.js:
module.exports = function(eleventyConfig) {
  // Copy `src/style.css` to `_site/style.css`
  eleventyConfig.addPassthroughCopy("src/style.css");

  return {
    // When a passthrough file is modified, rebuild the pages:
    passthroughFileCopy: true,
    dir: {
      input: "src",
      includes: "_includes",
      data: "_data",
      output: "_site"
    }
  };
};

Step 3: Add a blog #

Checkout branch 3-blog to see this next step. In this step, I create blog posts and an index of those posts.

  1. Create a /src/blog/ folder.
  2. Add our first post in that folder welcome-to-my-blog.md, remembering to set the layout and title:
---
layout: layout.njk
title: Welcome to my blog
---

# Welcome

These are profound thoughts.

We can now access it at http://localhost:8080/blog/welcome-to-my-blog/, but it would be nice to get some links on our home page for all our posts. For that, we should make a collection for our blog posts. We will do this using tags.

  1. Add a blog tag to our blog post's frontmatter:
---
layout: layout.njk
title: Welcome to my blog
tags: blog
---
  1. Change our /src/index.md file to use Nunjucks instead by changing .md to .njk and changing the current content to html:
---
layout: layout.njk
title: The Best Eleventy Demo TM
---

<h1>Yo Eleventy</h1>
<p>This site rocks.</p>
  1. Render a list of blogs on our index/home page (/src/index.njk) usink a Nunjucks for loop:
<ul>
{% for post in collections.blog %}
  <li><a href="{{ post.url }}">{{ post.data.title }}</a></li>
{% endfor %}
</ul>
  1. Add another post and see it magically appear!
  2. Add a "nav" to your home page so people can get back to it from the blog page. In /src/_includes/layout.njk inside the <body>:
<nav>
  <a href="/">Home</a>
</nav>

This is when I'd probably make another layout for a blog post so that the title is automatically rendered in its <h1>, but then this baby demo would be longer. :)

Moving Forward #

Once you've had a chance to play with collections and other forms of data in Eleventy, I recommend you check out my article Architecting data in Eleventy to learn more. It might be a bit much if this is your first time.

What else can Eleventy do? So much! Here's a list of some of my favorite features:

IndieWeb Eleventy JavaScript Jamstack

Hi, I'm Sia.

I'm a freelance performance engineer and web developer, and I'm available for your projects.

Hire me

You might also like

Webmentions

If you liked this article and think others should read it, please share it.

Likes 48 Reposts 9 Comments 2
mike ritter mike ritter

I am quite a bit past this, though it is helpful review. Looking forward to the Magnolia conference. I am enjoying 11ty for building out static site projects and demos. source

Sia Karamalegos Sia Karamalegos

Yep this is more for people with no experience source

These are webmentions via the IndieWeb and webmention.io. Mention this post from your site:

← Home