DEV Community

Cover image for Itsiest, Bitsiest Eleventy Tutorial
Sia Karamalegos
Sia Karamalegos

Posted on • Originally published at sia.codes

Itsiest, Bitsiest Eleventy Tutorial

#eleventy #javascript #webdev #tutorial

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

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!

Do you prefer learning by video? I included a walkthrough of this demo in my talk on Webmentions + Eleventy at Magnolia JS.

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"
    }
  };
};
Enter fullscreen mode Exit fullscreen mode

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:

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>
Enter fullscreen mode Exit fullscreen mode

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"
---
Enter fullscreen mode Exit fullscreen mode

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"
    }
  };
};
Enter fullscreen mode Exit fullscreen mode

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.
Enter fullscreen mode Exit fullscreen mode

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.

Tip: You can log data to your terminal using the log filter which is included in Eleventy for free! For example, {{ collections | log }} to see all your collections. Right now, we only have the all collection which contains all our pages (home and first blog post).

Add a blog tag to our blog post's frontmatter:

  ---
  layout: layout.njk
  title: Welcome to my blog
  tags: blog
  ---
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

Add another post and see it magically appear!

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>
Enter fullscreen mode Exit fullscreen mode

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:

This article was originally published on sia.codes. Head over there if you like this post and want to read others like it, or sign up for my newsletter to be notified of new posts!

Oldest comments (0)

Read next

borysshulyak profile image

High Level requirements and purposes

Boris Shulyak -

prast profile image

Launching a website offline without the Internet using Service Worker (English version)

Ramzan -

borysshulyak profile image

Basic Testing Conventions on my prjects

Boris Shulyak -

prasetyomuhdwi profile image

Setup path aliases in React + Vite + TS Project 🤓

Muhammad_Dwi_Prasetyo -