DEV Community: Sia Karamalegos

Itsiest, Bitsiest Eleventy Tutorial

Sia Karamalegos — Thu, 08 Jul 2021 20:10:54 +0000

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:

Start up the most minimal Eleventy project with one page (the main branch)
Add a layout and styles (the 2-layout-styles branch)
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:

Make a new directory
cd into it
npm init -y
Install Eleventy with npm install @11ty/eleventy
Edit the package.json to add a start script of npx @11ty/eleventy --serve and a build script of npx @11ty/eleventy.
Create index.md
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/:

Create /src/ and move index.md into it.
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:

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>

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:

Create /src/style.css. Add some CSS to that file.
Add <link rel="stylesheet" href="/style.css"> to the head of /src/_includes/layout.njk.
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.

Create a /src/blog/ folder.
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.

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
  ---

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>

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>

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>

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:

Generating pages based on a data set (JavaScript, JSON), like my individual game pages in my boardgame shelf site. Code
Creating layouts within layouts and template partials (like creating components)
Using filters and shortcodes to make reusable functions and code

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!

Adding Prettier to a Project

Sia Karamalegos — Thu, 01 Jul 2021 20:28:02 +0000

While working at a smaller dev shop, our team hit the point at which the inconsistent code formats between and within projects was becoming a pain. Our needs included:

A consistent linter/formatter for all projects in a particular language
An autoformatter so developers didn't spend time "fixing" linter errors
A tool readily available in tools like VS Code which could apply changes on save

We decided to go with Prettier. We also added a pre-commit hook to ensure that all code changes complied with the new authoritarianism.

I initially published this as a gist to help when setting up new projects at that company. Today, it was useful for a client I was working with, so I'm sharing it now in an article in case the same use case fits for you, and you'd like a handy reference.

The Steps

Most of these steps can be found in the docs and through other links in the docs.

A key step here is to run Prettier on all the files in a separate commit. You don't want to pollute all your future pull request diffs with formatting changes.

(1) Install prettier:

$ npm install --save-dev --save-exact prettier

(2) Create an empty config file to let tools know you're using Prettier:

$ echo {}> .prettierrc.json

(3) Create a .prettierignore file to let tools know which files NOT to format. node_modules are ignored by default. Some suggestions:

build
coverage
.package-lock.json
*.min.*

(4) Manually run Prettier to re-format all the files in the project:

$ npx prettier --write .

(5) Set up your code editor to auto-format on save for ease of use. See instructions for various editors.

(6) Set up commit hooks with pretty-quick and husky. First, install them as dev dependencies:

$ npm i --save-dev pretty-quick husky

(7) Finally, add the pre-commit instructions to your package.json file:

"husky": {
  "hooks": {
    "pre-commit": "pretty-quick --staged"
  }
},

Now when you commit your changes, files in the commit will automatically be formatted!

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!

Faster YouTube embeds in Eleventy

Sia Karamalegos — Wed, 07 Apr 2021 17:54:23 +0000

Video is great, but the default YouTube embed share is both bloated and not privacy-minded. I finally switched my YouTube embeds to lite-youtube-embed by Paul Irish, and it's fantastic. It loads "faster than a sneeze" and uses the no-cookie version by default.

This post will explain how to set up a reusable lite-youtube-embed "component" using Nunjucks partials in an Eleventy project.

Before implementing lite-youtube-embed, one of my pages using the default YouTube embed had a Lighthouse score of 71:

After implementing lite-youtube-embed, my performance score popped up to 97:

Step 1: Get the source code

This step will vary depending on how you currently load JavaScript in your Eleventy application. I try to keep my blog as minimal as possible, so I have no significant client-side JS. Thus, I chose to download the JavaScript file instead of adding the npm package and a bundle step. If you already have a bundler set up, then add the npm package instead.

These steps describe how to add it to an Eleventy project with no JavaScript files yet:

Add the source code JavaScript file to a /javascript/ folder in your project.
Update the Eleventy config to pass the /javascript/ folder through to our build:

// .eleventy.js
module.exports = function(eleventyConfig) {

  // Copy all files in the JavaScript folder to our output directory.
  eleventyConfig.addPassthroughCopy("src/javascript");

  // more config stuff...

Note: I choose to organize my source code in an /src/ folder (my input directory). If your code is in the root of your project, then ignore mentions of /src/ in this post.

Additionally, we need to grab the CSS from the source code. For simplicity, I copied it into my existing CSS file since the content wasn't that long. If your video looks weird after implementing, your project's existing styles are probably impacting it. For example, I had some iframe styles that caused the video to shift down inside its container.

YouTube partial

Now, we need to create a new template for a YouTube video. I'm using Nunjucks to create a video "component". In the /_includes/ folder, create a youtube.njk file with the following content:

<!-- src/_includes/youtube.njk -->

<!-- Load the JS only when the component is needed -->
<script src="/javascript/lite-yt-embed.js"></script>

<!-- Web component for lite-youtube-embed -->
<lite-youtube videoid="{{ videoId }}" style="background-image: url('https://i.ytimg.com/vi/{{ videoId }}/hqdefault.jpg');" {% if params %} params="{{ params }}"{% endif %}>
  <button type="button" class="lty-playbtn">
    <span class="lyt-visually-hidden">Play Video: {{ videoTitle }}</span>
  </button>
</lite-youtube>

The web component will use up to 3 parameters:

videoId - the id of the YouTube video which you can grab from its URL. For example, "XecoxR1ckbc" is the id of the video in this URL: https://www.youtube.com/embed/XecoxR1ckbc
videoTitle - the video title
params - optional params like start and end times

I chose to defer the YouTube script loading for progressive enhancement. Our tiny bit of JavaScript from lite-youtube-embed will always load. But, the larger code from YouTube will only load if a user clicks on the video to play it. See the readme if you'd like to always load the YouTube scripts regardless.

Using the new YouTube partial

Now that our set up is complete, we can use our new "component" in any file. First, we set the variables that pass through to the component, then we include the partial. This example also illustrates how to add a start and end time to the optional params:

<!-- In any other file (e.g., a blog post): -->
{% set videoTitle = "Vintage Bundles by Sia Karamalegos [ Magnolia JS ]" %}
{% set videoId = "Qkc8p4D6JM0" %}
{% set params = "start=10260&end=11280" %}
{% include 'youtube.njk' %}

You can see it in action in the original article on my blog.

What my source code looks like:

+{% set videoTitle = "Webmentions + Eleventy by Sia Karamalegos [ Jamstack Toronto ]" %}
+{% set videoId = "zjHb4xtnTvU" %}
+{% include 'youtube.njk' %}

What the compiled HTML looks like (Eleventy output):

<div class="videoWrapper">
  <iframe loading="lazy" title="Webmentions + Eleventy by Sia Karamalegos [ Jamstack Toronto ]" width="560" height="315" src="https://www.youtube.com/embed/zjHb4xtnTvU" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
</div>

Conclusion

Switching to lite-youtube-embed can greatly improve our load performance. It also better protects the privacy of our users. We can use HTML templates in Eleventy to create a YouTube video component, making reuse a breeze.

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!

Eleventy and Cloudinary images

Sia Karamalegos — Sat, 12 Dec 2020 04:32:25 +0000

I'm a huge fan of Cloudinary for media, and this was the first time I set it up on a site using Eleventy. In typical fashion, I wasn't satisfied with the existing solutions I found, so I decided to write my own.

Originally, I did not set up Cloudinary on my blog because I used to have just a handful of images, and I would create srcsets and formats manually using ImageMagick and cwebp. But then I got excited about using structured data for SEO, and the image generation job got a lot more complicated with more sizes and cropping.

In this post, first I'll go over how I think about serving responsive, performant images. Then, I'll show you how I implemented Cloudinary image hosting in Eleventy.

What's in an `<img>`?

Let's take a look at a "fully-loaded" image tag in HTML:

  <img src="pug_life.jpg"
    srcset="pug_life_600.jpg 600w, pug_life_300.jpg 300w,"
    sizes="(min-width: 760px) 600px, 300px"
    alt="Pug wearing a striped shirt"
    width="600"
    height="400"
    loading="lazy"
  >

Why did I include all those attributes? Let's take a look at each...

src - the image to display (required!)
srcset - for modern browsers, a set of candidate images and their widths in pixels
sizes - for modern browsers, how wide the image will be displayed at various screen widths
alt - description of the image
width - the image width
height - the image height
loading - optionally lazy-load images and iframes, caniuse

`srcset` and `sizes`

For modern browsers, we can give a set of images and instructions for how wide they will be displayed using srcset and sizes. This allows the browser to make the best decision on which image to load based on the user's screen width and device pixel ratio (DPR). For example, those nice Retina screens (DPR of 2) need images twice as wide as the slot we're putting them in if we still want them to look good.

The sizes attribute can be tricky to write correctly by hand. My favorite way of getting it (a.k.a, the lazy way), is to first give the image a srcset, then run the page through RespImageLint. RespImageLint is a nifty bookmarklet that will let you know how far off your images are in their size, and will also give us suggestions for the sizes attribute.

RespImageLint will suggest a sizes attribute if you provide a srcset

Layout Shift

To prevent layout shift once the image loads, we need to provide the browser with an aspect ratio. Currently, the way to do that is to set a height and width on the image in HTML. Use the original image's dimensions since the actual size doesn't matter, just the aspect ratio. Your CSS will control the actual height and width.

To prevent weird stretching, set an auto height in your CSS:

img {
  height: auto;
}

Jen Simmons recorded a great short video on this trick.

Lazy loading

We now have partial support for lazy loading images and iframes! If you set the loading attribute to lazy, the browser will use the IntersectionObserver to detect if a user scrolls near the image or iframe and only load it at that time.

At the time of writing, 78% of my blog's visitors are supported for images, so I'm implementing it now. Note that you should not lazy-load images that are in the viewport on initial load ("above the fold"), as this can negatively impact your performance scores.

The code

Now that you know how I think about images, I can explain my rational behind my solution. Some of the existing alternatives were Eleventy shortcodes that provided the full image tag based on the filename, alt, and a few other attributes. I wanted the ability to also provide all the attributes previously mentioned plus others like class.

The shortcode quickly became unwieldy with this many parameters, and I realized that the HTML itself was only marginally longer. Why not just use HTML? The onerous part of building responsive images, especially when hosting through Cloudinary, is setting the image urls and generating the srcsets.

Why not just use HTML?

Hence, I created shortcodes that do only that - generate the src and srcset, and everything else can be set as needed in the HTML:

  <img src="{% src "possum_film_director.jpg" %}"
    srcset="{% srcset "possum_film_director.jpg" %}"
    sizes="(min-width: 760px) 680px, 93.64vw"
    alt="Possum directing a movie"
    width="2953"
    height="2178"
    loading="lazy"
    class="super-great-style-class"
  >

I don't need a <picture> tag because Cloudinary can automatically serve the best image format based on the user's browser through the f_auto transformation.

If you found this article helpful, you can sign up for a free Cloudinary account with this link, and I'll get a few extra Cloudinary credits per month.

Shortcodes

For the shortcodes, I gave them smart default widths based on the styles for my site, but I allow an optional parameter to set them when I invoke the shortcode.

// _11ty/shortcodes.js
const CLOUDNAME = "[your Cloudinary cloud name]"
const FOLDER = "[optional asset folder in Cloudinary]"
const BASE_URL = `https://res.cloudinary.com/${CLOUDNAME}/image/upload/`;
const FALLBACK_WIDTHS = [ 300, 600, 680, 1360 ];
const FALLBACK_WIDTH = 680;

function getSrcset(file, widths) {
  const widthSet = widths ? widths : FALLBACK_WIDTHS
  return widthSet.map(width => {
    return `${getSrc(file, width)} ${width}w`;
  }).join(", ")
}

function getSrc(file, width) {
  return `${BASE_URL}q_auto,f_auto,w_${width ? width : FALLBACK_WIDTH}/${FOLDER}${file}`
}

module.exports = {
  srcset: (file, widths) => getSrcset(file, widths),
  src: (file, width) => getSrc(file, width),
}

The last step is to add the shortcodes to our Eleventy config:

// .eleventy.js
const { srcset, src } = require("./_11ty/shortcodes");

eleventyConfig.addShortcode('src', src);
eleventyConfig.addShortcode('srcset', srcset);

Voilà!

How do you use Eleventy with Cloudinary? I haven't turned this into a plugin yet. Should I?

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!

Architecting data in Eleventy

Sia Karamalegos — Thu, 11 Jun 2020 15:20:27 +0000

Eleventy is a static site generator that makes building static, performant websites a breeze. It uses JavaScript to build pages at build time, but does not require any JavaScript in the client to render them.

Eleventy's magic comes with powerful tools for data, but the data model can be a lot to conceptualize when you're new to Eleventy. In this post, I'll explain the hierarchy of the data that we can work with and how to access it. I'll use real-world examples for learners like me who understand concepts better when they see them applied in practice.

Disclaimer: opinions ahead! I'm going to focus more on the concepts that will help you in decision making. Links are provided if you want to dive into the details of any one concept. I hope to make a second post in this series that talks about manipulating data, so stay tuned!

The examples here will use HTML, Markdown, JavaScript, JSON, and Nunjucks. For reference, I'm using Eleventy version 0.11.0 as it has a few cool new tools.

Getting started

The Eleventy docs are a key place to start understanding the different features. We're going to take these a few steps further to give you an over-arching understanding of how it all works together.

To follow along, you can find the code in my eleventy-data-tutorial repo. The main branch contains a bare-bones starting Eleventy app with an index.html and a single layout.

How do I see my data??

As someone used to building apps with front-end frameworks or client-side JavaScript, I felt like a deer in the headlights when I first wanted to "see" my data. Eleventy is using JavaScript to build full HTML pages in Node, not render them in a browser. This means we don't have access to browser dev tools like the debugger or the browser console.

We do have access to the terminal/command line console and the rendered pages. New in version 0.11.0, we have access to a log "universal filter" which performs a console.log() accessible in our terminal (remember, we're in Node land!). Filters are functions, and we write them in our templates by first listing the first parameter, then the filter name. If the filter accepts more than one parameter, we add them in parentheses:

<!-- _includes/layout.njk -->

<!-- console.log the page data -->
{{ page | log }}

<!-- run myCustomFilter on 2 params, the title data and anotherParam -->
{{ title | myCustomFilter(anotherParam) }}

I make heavy use of the log filter to debug my builds (since most of my bugs are from not handling the data correctly), and it's great to have this built in now. Another option is to output the data to the rendered page, but that doesn't work with complex objects.

Note that you can also run Eleventy in debugging mode for other information. I'm still learning how to best use this tool.

Page data

Every page has a page object available in the template which includes data like input and output file paths, the file slug, and URL. See it in your command line by logging it:

<!-- _includes/layout.njk -->

<!-- console.log the page data -->
{{ page | log }}

And your output will look something like this:

{
  date: 2020-05-13T19:31:02.218Z,
  inputPath: './src/index.html',
  fileSlug: '',
  filePathStem: '/index',
  url: '/',
  outputPath: '_site/index.html'
}

Note that the file slug is an empty string for the index file. If I add a new folder called /posts with a file called my-first-post.md, I get this page data:

{
  date: 2020-05-13T20:12:20.649Z,
  inputPath: './src/posts/my-first-post.md',
  fileSlug: 'my-first-post',
  filePathStem: '/posts/my-first-post',
  url: '/posts/my-first-post/',
  outputPath: '_site/posts/my-first-post/index.html'
}

By default, Eleventy builds pages based on your file and directory structure. In the 1-page-data branch of the repo, you can see the pages logged to the console if you run npm start.

Before we move on to custom data, note that Eleventy also provides pagination data to a page. Pagination is a very specific use case, so I won't cover it here. Read more about pagination in the docs.

Collection data

With collections, we are upping the magicalness of Eleventy. Collections are groups of pages that are grouped by tags*. To conceptualize this, think of a traditional blog with posts on multiple topics. One post might be tagged JavaScript while another might be tagged both JavaScript and HTML. If you like relational databases, think of tags and pages as having a many-to-many relationship.

Collections are useful for rendering lists of pages that include the ability to navigate to those pages. For example, an index page for your blog posts or a list of pages with the same content tag.

Collections are JavaScript objects, and each key is the tag name. The value for each key is an array of pages. Tags are set using the data hierarchy which I'll get to in a bit, and this is what the collections object looks like if we log it from our home page:

{
  // By default, the `all` key is created and includes all pages.
  all: [
    {
      template: [Template],
      inputPath: './src/index.html',
      fileSlug: '',
      filePathStem: '/index',
      data: [Object],
      date: 2020-05-13T19:31:02.218Z,
      outputPath: '_site/index.html',
      url: '/',
      templateContent: [Getter/Setter]
    },
    // ...rest of all pages
  // Pages tagged as "posts"
  posts: [
    {
      template: [Template],
      inputPath: './src/posts/my-first-post.md',
      fileSlug: 'my-first-post',
      filePathStem: '/posts/my-first-post',
      data: [Object],
      date: 2020-05-13T20:12:20.649Z,
      outputPath: '_site/posts/my-first-post/index.html',
      url: '/posts/my-first-post/',
      templateContent: [Getter/Setter]
    },
    // ...rest of posts
  podcasts: [
    {
      template: [Template],
      inputPath: './src/podcasts/my-first-podcast.md',
      fileSlug: 'my-first-podcast',
      filePathStem: '/podcasts/my-first-podcast',
      data: [Object],
      date: 2020-05-13T20:23:43.665Z,
      outputPath: '_site/podcasts/my-first-podcast/index.html',
      url: '/podcasts/my-first-podcast/',
      templateContent: [Getter/Setter]
    }
  ],
  JavaScript: [
    {
      template: [Template],
      inputPath: './src/podcasts/my-first-podcast.md',
      fileSlug: 'my-first-podcast',
      filePathStem: '/podcasts/my-first-podcast',
      data: [Object],
      date: 2020-05-13T20:23:43.665Z,
      outputPath: '_site/podcasts/my-first-podcast/index.html',
      url: '/podcasts/my-first-podcast/',
      templateContent: [Getter/Setter]
    },
    {
      template: [Template],
      inputPath: './src/posts/my-second-post.md',
      fileSlug: 'my-second-post',
      filePathStem: '/posts/my-second-post',
      data: [Object],
      date: 2020-05-13T20:24:27.709Z,
      outputPath: '_site/posts/my-second-post/index.html',
      url: '/posts/my-second-post/',
      templateContent: [Getter/Setter]
    }
  ]
}

Note that:

The collections object by default includes an all key which includes all pages.
I have tagged by both content type (posts vs podcasts) which matches my routing, and by topic (JavaScript).

You are not limited by how you want to use tags and collections.

The benefit collections give you is grouping pages by a string key which gives you access to all group members' urls and other data.

A new feature in version 0.11.0 is a universal filter for giving you previous and next items in a collection. By default, these are sorted by file creation date which can be overridden.

In the 2-collections branch of the repo, I created index pages for both the podcasts and posts, and added those index pages to the site's navbar, all using collections.

* Custom collections

Tags are the most common way of creating collections, but you can actually create custom collections using JavaScript in your Eleventy config. Phil Hawksworth uses this feature in his blog to create a collection of the tags themselves as well as create a collection of all items in the blog folder, among other things:

// .eleventy.js
module.exports = function(eleventyConfig) {

    // Assemble some collections
  eleventyConfig.addCollection("tagList", require("./src/site/_filters/getTagList.js"));
  eleventyConfig.addCollection("posts", function(collection) {
    return collection.getFilteredByGlob("src/site/blog/*.md").reverse();
  });
  eleventyConfig.addCollection("cards", function(collection) {
    return collection.getAll().filter(function(item) {
      return "card" in item.data;
    });
  });

};

See Phil's source code.

Template data

So far, we've only been using the data supplied by Eleventy with only a few custom data elements that I snuck in while you weren't looking. 👀 Let's take a look at those now.

In /src/posts/my-first-post.md, I use YAML front matter to set a few data attributes for my page - the title, which layout to use, and which tags should be applied to add this page to those collections:

# /src/posts/my-first-post.md
---
title: "My first blog post"
layout: post.njk
tags: ['posts']
---

Bootcamp .NET npm branch Agile grep native senior. Database webpack
pairing build tool pull request imagemagick. AWS injection OOP
stack Dijkstra looks good to me Firefox bike-shedding scrum master.

We learned about tags already; layout is a similar special template data key in Eleventy which tells it which layout file to use for your page (found in a /_includes/ folder). Other special template data keys for templates include permalink, date, and more.

Custom data and the data hierarchy

Finally, we come to custom data. In the example above, I set a title attribute in my front matter. This is not data automatically supplied nor used by Eleventy. It is completely custom. In this case, I use it to populate both my webpage's <title> element and the primary heading, or <h1>. Custom data you set in this manner is available directly in a template using the name you gave it:

<!-- /src/_includes/post.njk -->
--------
layout: layout.njk
--------

<h1>{{ title }}</h1>
{{ content | safe }}

Eleventy uses a data hierarchy so that you can set defaults or inheritance and then override them:

Computed Data
Front Matter Data in a Template
Front Matter Data in Layouts
Template Data Files
Directory Data Files (and ascending Parent Directories)
Global Data Files

In my example, we're using #2 in the hierarchy... and also #3 - you have to go to my highest-level layout to find it:

<!-- /src/_includes/layout.njk -->
--------
title: My default layout title
--------
<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{{ title }}</title>
  <!-- ...rest of html -->

The title set in my-first-post.md overrides the title set in the layout. If a title attribute is missing, then the default one set in layout.njk is used. Wicked smart!

Now that we know about this data hierarchy, we can clean up some of our front matter by using a directory data file. Here's where we get a little muddy in our explanation since you can use the data hierarchy for template data too, not just custom data. In my /posts/ folder, I can create a file with the same name as the folder and with either a .json, .11tydata.json or .11tydata.js extension that applies that data to all the files (i.e., templates/pages) in that folder.

We can use this to set the layout file and the posts tag to all the files in the /posts/ folder, then remove those from the individual post files' front matter:

// /src/posts/posts.json
{
  "layout": "post.njk",
  "tags": [
    "posts"
  ]
}

# /src/posts/my-first-post.md
--------
title: My first blog post
--------

Bootcamp .NET npm branch Agile grep native senior. Database webpack
pairing build tool pull request imagemagick. AWS injection OOP
stack Dijkstra looks good to me Firefox bike-shedding scrum master.

Great, we're DRYing up the files! There's only one problem - the merge messed up our content tags. Our second blog post added a JavaScript content tag. That overrode the posts tag. Luckily, we can use data deep merge to instead merge data that is an object or array:

// .eleventy.js
module.exports = function(eleventyConfig) {
  eleventyConfig.setDataDeepMerge(true);
};

Now our posts index page, /src/posts/index.njk, is showing up in our posts collection list because it's inheriting the tag from the directory. We can fix this by renaming it posts.njk and moving it up to the /src/ directory. This move preserves the original routing due to the magic of Eleventy's directory- and file-based build method.

You can find the code for this section in the 3-data-hierarchy branch. This was just one example of using the data hierarchy - you should definitely check out the data hierarchy docs to learn about the other options too. I could spend loads of time explaining the hierarchy, but that would make it seem like the most important concept in all of Eleventy. Just know that it gives you the ability to inherit or scope data as you please. So if you need more precision on managing inheritance or scope, dive down on that concept more.

What custom data is even available in a view?

You're trying to build a page, but you can't figure out "where" your new variable that you thought you set. I haven't found a way to log everything available in a page - something akin to self or this. I have found a way to hack this with collections. For each item in a collection, you can log the item.data which will show the special Eleventy data attributes as well as your own custom ones:

{
  pkg: {
    // package.json data
  },
  layout: 'post.njk',
  tags: [ 'posts', 'JavaScript' ],
  // Look! It's our custom title attribute:
  title: 'My second blog post',
  page: {
    date: 2020-05-13T20:24:27.709Z,
    inputPath: './src/posts/my-second-post.md',
    fileSlug: 'my-second-post',
    filePathStem: '/posts/my-second-post',
    url: '/posts/my-second-post/',
    outputPath: '_site/posts/my-second-post/index.html'
  },
  collections: {
    all: [ [Object], [Object], [Object], [Object], [Object], [Object] ],
    nav: [ [Object], [Object] ],
    podcasts: [ [Object] ],
    JavaScript: [ [Object], [Object] ],
    posts: [ [Object], [Object] ]
  }
}

If you know of a way to do this more easily, please share, and I'll update this post!

Custom Data with a capital D

The data hierarchy and examples I gave above are great for providing smart defaults, inheritance, and merging basic page data. But what about what I like to call "Data with a capital D"? Do you need to render something that is dependent on a large data object or array? Do you need to fetch data from another URL before statically rendering it? Do you need to manipulate some data to make it easier to use?

The data hierarchy technically handles that too, but we usually use either global data files, or maybe directory- or file-specific data files. Three examples I have implemented in Eleventy include:

Showing my upcoming and past speaking events on sia.codes/speaking based on global data files talks.js and events.js (events can have many talks and talks can be repeated at different events).
Fetching webmentions for all my blog posts on sia.codes to show them at the bottom of an article with re-builds triggered every 4 hours to pull in new ones (example article with webmentions at the bottom).
Organizing courses, modules, and lessons in a new Jamstack course management system. (I hope to release an open source version soon!)

I'll focus on the global data file method here. Data in files located in a /_data/ directory is globally accessible in all pages using the filename. Your files can either be JSON, or you can use module.exports from a JavaScript file (actually, it can handle more data types if you don't like JavaScript 😅). In our repo, branch 4-big-d-data, I created a dogs data file:

// /src/_data/dogs.js
module.exports = [
  {
    name: 'Harry',
    breed: 'Jack Russell terrier',
    favoritePasttime: 'finding hidey holes',
    stinkLevel: 3,
  },
  {
    name: 'Priscilla',
    breed: 'Australian shepherd',
    favoritePasttime: 'starting farty parties',
    stinkLevel: 1,
  }
]

If I then log dogs from any of my template/page files, I can see that exact data in my terminal. In this case, it is an array, so I can loop over it to render my dog info:

<!-- /src/dogs.njk -->
--------
layout: layout.njk
title: Pup party
tags: ['nav']
--------

<h1>My doggos</h1>
<p>Much floof. Much fart.</p>

<ul>
  {% for dog in dogs %}
  <li>
    {{ dog.name }} is a/an {{ dog.breed }} and likes {{ dog.favoritePasttime }}.
    {{ dog.name }}'s stink level from 1-5 is a {{ dog.stinkLevel }}.
  </li>
  {% endfor %}
</ul>

<!-- TODO: delete random logs -->
{{ dogs | log }}

If you needed to fetch data, you could use a JavaScript file and return an async function for your module.exports. It's a bit complex, but my webmentions code is an example of this. If you're interested in the details, I wrote up a full tutorial on adding webmentions to an Eleventy site.

If you want to manipulate data before using it, you could "just use JavaScript". For example, in my online course project, I import my course>module>lesson hierarchy data from /_data/courses.js into another /_data/lessonPrevNext.js file to manually set a previous and next lesson since the sort order is a bit more nuanced. I wanted one source of truth, but needed something easier to work with in my views. Computed data is another new feature in 0.11.0 that you can use as well.

Summary

Eleventy is a powerful static site generator with a lot of flexibilty in how to handle data. It's so flexible that sometimes your options for architecting data can be overwhelming. The primary ways I use data in developing Eleventy apps are:

page data - includes attributes like url and file slug
collections - groups of pages/templates often to generate a list of links
template data using the data hierarchy - special template data like layout, permalinks, tags, and dates as well as custom "small" data like titles and whether a page should be included in a nav bar
global "big" data (though scope can be narrowed) - larger, more complex data that is easier to manage in a separate file and can also be fetched asynchronously (also technically still uses the data hieararchy)

To see your data, use the log universal filter.

Have you used data in a unique way in your Eleventy sites? If so, I'd love to see your examples!

Thanks

Special thanks to Chris Guzman, Aaron Peters, David Rhoden, and Phil Hawksworth for giving me their time and feedback!

I apologize for the cover image abomination. It is a mash up of two great images on Unsplash by Mikell Darling and Yingchih.

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!

Vintage Bundles talk at Magnolia JS

Sia Karamalegos — Tue, 21 Apr 2020 21:03:19 +0000

More developers are starting to understand that web performance matters. From higher mobile search rankings to bottom-line revenue impacts, performance can make or break your web app. However, fixing performance can feel like a quagmire of expert-level nuanced understanding on so many topics. What would you think if I told you you could cut your JavaScript bundle size up to 50% by doing one thing only? Nearly 90% of worldwide web traffic runs on modern browsers, but we're transpiling all of our JavaScript down to ES5. That transpilation has a cost.

In this talk, we'll learn about differential serving, or serving modern bundles to modern browsers and legacy, transpiled bundles to older browsers. We'll talk about strategies, what to watch out for, and how to implement it using webpack. This talk is framework agnostic, and it's best if you have at least a basic understand of JavaScript.

Magnolia JS was my second virtual conference, and I had a blast participating. This video is the full day 1 video, and you can find my talk at 2:51:00. Check out the other talks that day too! Enjoy!

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!

Responsive, Performant Images for the Web

Sia Karamalegos — Fri, 17 Apr 2020 20:55:34 +0000

Want to learn how to make your images more responsive and more performant? Haven't gotten a chance to read that book/article/doc on web performance for images yet?

I spoke at my first virtual conference, PerfMatters Conf, and luckily they recorded it. This talk is a great intro into all things images for the web. Enjoy!

Images account for 50% of the bytes downloaded to load a website. How can you make sure that your users only download the smallest image necessary while preserving image quality? In this talk, we'll focus on the underlying concepts in HTML and CSS for serving responsive images, which you can take with you no matter which tool you use. Which file formats suit which image types best? How can you use art direction in images to show the best image for a viewport layout?

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!

How to build a website in 2020

Sia Karamalegos — Tue, 11 Feb 2020 15:07:09 +0000

Step 1: Buy a domain. You might have a problem if you already have 20 domains waiting to be used, but that's okay. Feel free to buy more domains. You never know when you might need that perfect domain name. P.S. zeit.co has a great domain search tool with hacks. Now I've just enabled your habit. You're welcome.

Step 2a: Engage in Twitter debates about how JavaScript is ruining the web and which static site generators are best. Do this for 4 months.

Step 3: Take an entire course to get better at design. Spend 5 hours generating an HSLa exploration CodePen to visualize something that already exists. Bemoan color systems and values. Read a shout-out tweet about best conference talks that happen to be about React and color. Find a tool that does it way better than you.

Step 2b: Eventually some rando will tell you about Eleventy, and you're like "sounds brilliant". Repeat step 2a.

Step 4: Clone that starter repo and fire it up. Waste 17 hours trying to figure out how to implement some esoteric design feature no one will notice. "Fuck, it's midnight on a Friday, why am I still doing this?" On Monday, "add a circle".

Step 5: Let's do dark mode.

Step 6: (Six hours later) Let's not do dark mode.

Step 7: Look at other people's sites in envy.

Step 8: Write the actual content.

Step 9: Join the Learn with Jason livestream on variable fonts. "Oh that's cool, must add."

Step 10: Edit the color scheme 20 more times. Play with the design and variable fonts. Open Firefox because the font dev tools are 🔥. Go blind because Firefox oversaturated the colors. Recover from blindness, and edit the colors again.

Step 11: Sees how CSS Tricks implemented dark mode and admire how well they did it. Silently close the tab.

Step 12: Launch! Ugh, non-responsive iframes and bad break points. Run Axe. Feel like a terrible person. Fix issues (and edit colors again).

Step 13: 5 months later, write a blog post.

Note to self: next time, just hire a designer.

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!

Day 26 of⚡️ #30DaysOfWebPerf ⚡️: Tasks

Sia Karamalegos — Wed, 18 Dec 2019 15:21:06 +0000

Liquid error: internal

Sia Karamalegos

@thegreengreek

So what are the tasks?

- Minify/uglify JS, CSS, and HTML (build)
- Compress using gzip or brotli (build or deploy, it depends)
- Set caching headers (deploy)
- Code splitting (build)
- Lazy and/or dynamic loading (codebase)
- Tree shaking (codebase and build)
- etc.

15:17 PM - 18 Dec 2019

Sia Karamalegos

@thegreengreek

It's a lot to learn - too much for one tweet thread.

Start with your measurement tools (Day 1) to see what your worst offenders are, and prioritize setting up those tasks first.

Breaking down the problem this way makes it much more manageable.

15:17 PM - 18 Dec 2019

Sia Karamalegos

@thegreengreek

[gif alt: small child throwing adult in martial arts class]

15:17 PM - 18 Dec 2019

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!

Day 25 of⚡️ #30DaysOfWebPerf ⚡️: Jank

Sia Karamalegos — Tue, 17 Dec 2019 15:35:14 +0000

Liquid error: internal

Sia Karamalegos

@thegreengreek

JavaScript can cause jank when we have long running scripts on the main thread. We theoretically have about 16 ms to process an event, but in reality the browser needs some of that time, so we only have about 10 ms.

15:29 PM - 17 Dec 2019

Sia Karamalegos

@thegreengreek

Styles & animations also cause jank. The render pipeline is more expensive the further upstream you affect something:

JS > Calculate > Layout > Paint > Composite

opacity & transform affect Composite, so they are cheap to use vs width which affects Layout csstriggers.com

15:29 PM - 17 Dec 2019

Sia Karamalegos

@thegreengreek

More resources:

afasterweb.com/2015/08/29/wha…

developers.google.com/web/fundamenta…

15:29 PM - 17 Dec 2019

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!

Day 24 of⚡️ #30DaysOfWebPerf ⚡️: Timing APIs

Sia Karamalegos — Mon, 16 Dec 2019 21:10:57 +0000

Liquid error: internal

Sia Karamalegos

@thegreengreek

Luckily, the User Timing API exists just for this purpose!

You set "marks" as points in time to reference, then you can measure the difference between various "marks" with a "measure" to get a duration.

This API is available for 95% of users globally today.

21:06 PM - 16 Dec 2019

Sia Karamalegos

@thegreengreek

The Navigation and Resource Timing APIs are similar and give you detailed data on the document and its assets.

To preview the data, load a page and in the console type, for example:

performance.getEntries()
performance.getEntriesByType('resource')

youtube.com/watch?v=BAeghS…

21:06 PM - 16 Dec 2019

Sia Karamalegos

@thegreengreek

Here are some of my favorite resources for learning both:
developers.google.com/web/fundamenta…

keycdn.com/blog/user-timi…

21:06 PM - 16 Dec 2019

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!

Day 23 of⚡️ #30DaysOfWebPerf ⚡️: Culture of Performance

Sia Karamalegos — Fri, 13 Dec 2019 17:47:59 +0000

For Day 23:

Liquid error: internal

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!

DEV Community: Sia Karamalegos

Itsiest, Bitsiest Eleventy Tutorial

Taking a step back

Step 2: Add a layout and styles

Step 3: Add a blog

Moving Forward

Adding Prettier to a Project

The Steps

Faster YouTube embeds in Eleventy

Step 1: Get the source code

YouTube partial

Using the new YouTube partial

Conclusion

Eleventy and Cloudinary images

What's in an <img>?

srcset and sizes

Layout Shift

Lazy loading

The code

Shortcodes

Architecting data in Eleventy

Getting started

How do I see my data??

Page data

Collection data

* Custom collections

Template data

Custom data and the data hierarchy

What custom data is even available in a view?

Custom Data with a capital D

Summary

Thanks

Vintage Bundles talk at Magnolia JS

Responsive, Performant Images for the Web

How to build a website in 2020

Day 26 of⚡️ #30DaysOfWebPerf ⚡️: Tasks

Day 25 of⚡️ #30DaysOfWebPerf ⚡️: Jank

Day 24 of⚡️ #30DaysOfWebPerf ⚡️: Timing APIs

Day 23 of⚡️ #30DaysOfWebPerf ⚡️: Culture of Performance

What's in an `<img>`?

`srcset` and `sizes`