Eleventy Quick Tips

Quick Tip: Draft Posts using Computed Data

2023-01-24T06:00:00Z

This example has been simplified and moved to the addPreprocessor documentation page. You can view the previous version of this page on the v2 documentation.

Quick Tip: Use local plugins to reduce config file size

2022-02-20T06:00:00Z

Is your .eleventy.js file getting too large? You can create your own plugin to move some code out.

First, create a plugin file. We recommend creating a config or _config folder in your project to store config files in. Make sure that folder isn’t getting copied out to your built site (via ignores). Then create a file in that folder. It doesn’t matter what you name it.

config/local-plugin.js

ESM CommonJS

export default function(eleventyConfig) {
	// Move any code from `eleventy.config.js` here.
	// Use eleventyConfig as you would in your top-level config file
}

module.exports = function(eleventyConfig) {
	// Move any code from `eleventy.config.js` here.
	// Use eleventyConfig as you would in your top-level config file
}

Any variables defined in your eleventy.config.js file will not be available to your plugin. Consider moving those variables into your plugin file, or passing them in as options.

Next, use the addPlugin method:

eleventy.config.js

ESM CommonJS

import localPlugin from "./config/local-plugin.js";

export default function(eleventyConfig) {
	eleventyConfig.addPlugin(localPlugin);
}

const localPlugin = require("./config/local-plugin.js");

module.exports = function(eleventyConfig) {
	eleventyConfig.addPlugin(localPlugin);
}

Quick Tip: Transform Global Data using an `eleventyComputed.js` Global Data File

2020-11-01T05:00:00Z

You can generate multiple data cascade elements in one eleventyComputed.js file. Following is a working example.

This example generates data cascade elements from multiple .json files in the global data directory.

Assume you have data files named links.json and copyrights.json, and you only want to extract a portion of the json object. In this case, the entry element contains the useful data in the json object, and is a child of the feed element in this case.

The corresponding eleventyComputed.js file contents can look like the following:

_data/eleventyComputed.js

ESM CommonJS

export default {
	myCopyrights: (data) => {
		return data.copyrights.feed.entry;
	},
	myLinks: (data) => {
		return data.links.feed.entry;
	},
};

module.exports = {
	myCopyrights: (data) => {
		return data.copyrights.feed.entry;
	},
	myLinks: (data) => {
		return data.links.feed.entry;
	},
};

Quick Tip: Cache Data Requests

2020-04-23T05:00:00Z

Read the full documentation at the eleventy-fetch plugin page.

In Quick Tip #007, we described a method to fetch data from an API at build time (in this example it was GitHub Stargazers) to display on your site.

However, if you’re working on your site locally, you probably don’t want every Eleventy build to make a request to an external API call. You’d hit the rate limit pretty quickly (on GitHub, 60 per hour) and each request would slow down your build times!

Now there is an easier way. You can use the eleventy-fetch utility to cache these requests to save on both API limits and build performance!

npm install @11ty/eleventy-fetch

Features

Makes at most one network request in the duration time span—save on both your API limit count and your build time!
Easy graceful handling of bad network requests to an API.
If your cache expires and it makes another request, and that request fails—it automatically falls back to the expired cache entry! This is especially useful if you’re developing without a network connection (airplane-driven-development)—your site will work the same as it did with the network connection—no changes required to your local development environment.

Example

This code is currently in use on the Eleventy web site to display GitHub stars in the footer. Check out the full source code.

ESM CommonJS

import Fetch from "@11ty/eleventy-fetch";

export default async function () {
	// https://developer.github.com/v3/repos/#get
	let json = await Fetch("https://api.github.com/repos/11ty/eleventy", {
		duration: "1d", // 1 day
		type: "json", // also supports "text" or "buffer"
	});

	return {
		stargazers: json.stargazers_count,
	};
};

const Fetch = require("@11ty/eleventy-fetch");

module.exports = async function () {
	// https://developer.github.com/v3/repos/#get
	let json = await Fetch("https://api.github.com/repos/11ty/eleventy", {
		duration: "1d", // 1 day
		type: "json", // also supports "text" or "buffer"
	});

	return {
		stargazers: json.stargazers_count,
	};
};

Take note that if you’re using this on a hosted build server, it may not maintain updates to the cache and will likely re-run every time. You can learn how to persist this cache on your build server.

Otherwise, current GitHub rate limits are limited to 60 requests per hour, so this will only be a problem if you do more than 60 Netlify builds in an hour. The npm API doesn’t seem to have a hard limit.

Failing Even More Gracefully

Wrap the above code in a nice try catch allows you to return a fake data set if the very first request fails (no expired cache entry is available). Note that if there is already an expired cache entry available, we use that instead.

ESM CommonJS

import Fetch from "@11ty/eleventy-fetch";

export default async function () {
	try {
		// https://developer.github.com/v3/repos/#get
		let json = await Fetch(
			"https://api.github.com/repos/11ty/eleventy",
			{
				duration: "1d", // 1 day
				type: "json", // also supports "text" or "buffer"
			}
		);

		return {
			stargazers: json.stargazers_count,
		};
	} catch (e) {
		console.log("Failed getting GitHub stargazers count, returning 0");
		return {
			stargazers: 0,
		};
	}
};

const Fetch = require("@11ty/eleventy-fetch");

module.exports = async function () {
	try {
		// https://developer.github.com/v3/repos/#get
		let json = await Fetch(
			"https://api.github.com/repos/11ty/eleventy",
			{
				duration: "1d", // 1 day
				type: "json", // also supports "text" or "buffer"
			}
		);

		return {
			stargazers: json.stargazers_count,
		};
	} catch (e) {
		console.log("Failed getting GitHub stargazers count, returning 0");
		return {
			stargazers: 0,
		};
	}
};

Quick Tip: Trigger a Netlify Build Every Day

2019-02-01T06:00:00Z

In Quick Tip #007 we talked about migrating away from using a Client-side third-party JavaScript widget to display GitHub stargazer counts and towards a Data fetched at Build time approach.

Updating this data at build time means that the data isn’t necessarily “live” (although the counts are likely cached at by at least one of the upstream dependencies of this widget, with a frequency that is out of your control).

I’m comfortable with these numbers being a little delayed (more than the JS widget method was) and with this new approach I get more control over the frequency of updates BUT I do probably want to run the build at least once a day. To do this, I used an IFTTT applet to trigger my Netlify build to run every morning using Netlify’s Build Hooks.

Many other services also provide build hooks and/or scheduled builds!

Heavily inspired by Phil Hawksworth’s work on RSS Jamstack.

Step 1 Create a Build Hook

Go into your Netlify site’s Build & Deploy settings
Select Continuous Deployment
Add a Build hook
Name it Deploy every day (or whatever you’d like)
I selected the main branch for my site.
Save this and it will provide you with a long URL a la https://api.netlify.com/build_hooks/SOME_ID_HERE. This is the URL you want.

Step 2 Schedule the Hook Trigger

Here are a few options to trigger your build hook:

Use cron-job.org to dynamically trigger your build hook.
Use IFTTT (mini-tutorial below).

Mini-Tutorials

IFTTT

Go to New Applet on ifttt.com
Click +this
Select the Date & Time service
Select the Every day at option (or whatever frequency you’d like)
Select the time you’d like the build to run.
Click +that
Select the Webhooks service
Select the Make a web request option
For the URL field, use the Build Hook URL you’ve already retrieved from Netlify.
For the Method field, choose POST.
For the Content Type field, choose application/x-www-form-urlencoded.
For the Body field, type {}.
Click the Create action button.
Click Finish.

Quick Tip: Fetch GitHub Stargazers Count (and More) at Build Time

2019-01-31T06:00:00Z

Older iterations of this website used a third party JavaScript widget to show the number of GitHub Stars the project currently had. You can see it in action on the versioned docs for 0.7.1 (scroll to the bottom).

This was in fact the only <script> tag on the entire 11ty.dev web site and it was from a third party. Naturally, it needed to be annihilated.

Let’s change up our architecture to ruthlessly eliminate this client-side JavaScript.

Get the Stargazers Count from the GitHub API

Read more at the GitHub API documentation.

This is a bit different from our client-side implementation because this data is only updated as often as your build runs. This is implemented using a global JavaScript data file at _data/github.js.

Install new dependencies: npm install node-fetch
Read more about node-fetch
It’s better to use the Eleventy Fetch utility instead, which will cache your fetch results to avoid hitting the GitHub API on every build.
- Related Quick Tip: Cache Data Requests

_data/github.js

ESM CommonJS

import fetch from "node-fetch";

export default async function () {
	console.log("Fetching new github stargazers count…");

	// GitHub API: https://developer.github.com/v3/repos/#get
	let res = await fetch("https://api.github.com/repos/11ty/eleventy");
	let json = await res.json();

	// prune the data to return only what we want
	return {
		stargazers: json.stargazers_count,
	};
};

const fetch = require("node-fetch");

module.exports = async function () {
	console.log("Fetching new github stargazers count…");

	// GitHub API: https://developer.github.com/v3/repos/#get
	let res = await fetch("https://api.github.com/repos/11ty/eleventy");
	let json = await res.json();

	// prune the data to return only what we want
	return {
		stargazers: json.stargazers_count,
	};
};

Now in your templates you can output the stargazers count with:

Syntax Liquid, Nunjucks

{{ github.stargazers }} GitHub Stars

which outputs

1515 GitHub Stars

Bonus: I created a humanReadableNum filter) using the human-readable-numbers package to format the number.

More Examples

You can look in the footer of this page to see examples of this in use on this very web site. I used it for:

NPM Download Count
GitHub Stargazers Count
Twitter Followers Count (careful here, this one is super brittle but Twitter’s API is historically anti-developer so 😇)

These all use the recommended caching mechanism described in the next section.

Recommended: Cache the Data to the File System

It is highly recommended to cache your API call data to the file system so that you aren’t making a ton of requests to an API with every build. Luckily, we have a Quick Tip on how to Cache your Data Requests!

Update Counts Daily

If you want to update these counts automatically every day, read Quick Tip #008—Trigger a Netlify Build Every Day with IFTTT.

Quick Tip: Adding a 404 Not Found Page to your Static Site

2018-09-20T05:00:00Z

A 404: Not Found page is a pretty standard thing on the web. It’s particularly useful when someone shares a broken or mistyped link. You don’t need dynamic middleware to do this, it’s pretty easy to add to a statically generated site. There are a few options, depending on your web host:

But first let’s make our 404.html template:

---
title: Oops! Not Found
permalink: 404.html
---

<!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>
		<p>
			This is where you should tell the user how to find their content. Maybe on
			the <a href="/">home page?</a>
		</p>
	</body>
</html>

Eleventy will output this template to 404.html.

There is no step two if you’re using one of the following hosts (a 404.html file in your output directory is all you need):

Netlify even has lovely multi-language 404 page support too using Redirects.

.htaccess

For other hosts, if you use .htaccess for configuration you can use ErrorDocument. Make sure your root directory matches here!

ErrorDocument 404 /404.html

With `--serve`

If you’re using the new Eleventy Dev Server Added in v2.0.0, the 404.html convention is now provided to you for free!

Quick Tip: Super Simple CSS Concatenation

2018-06-27T05:00:00Z

In some situations you may want to concatenate content files together into a single top level template. Maybe you want to create a single CSS file with all of your component CSS inside.

Consider this sample theme.njk file:

---
permalink: theme.css
---

{% include "components/header.css" %}
{% include "components/footer.css" %}

That’s an easy way to concatenate files and control the include order.

You might imagine creating an include-all Shortcode that uses fast-glob to include a glob of files like {% include-all "components/*.css" %}, but that’s an exercise left to the reader!

Capture and Minify

In our Inline CSS Quick Tip, we discussed how to capture and minify a CSS file. This approach can be modified, of course, to capture multiple includes too!

<!-- capture the CSS content as a Nunjucks variable -->
{% set css %}
{% include "components/header.css" %}
{% include "components/footer.css" %}
{% endset %}
<!-- feed it through our cssmin filter to minify -->
<style>
	{{ css | cssmin | safe }}
</style>

Warning about Content Security Policy

WARNING

If you are using a Content Security Policy on your website, make sure the style-src directive allows 'unsafe-inline'. Otherwise, your inline CSS will not load.

Work with what you have

Of course, Eleventy has no desire to replace your existing build pipeline. This is just a super simple example if you want something up and running quickly.

That said, Eleventy wants to work with what you have. As an example, the EleventyOne project scaffold is a fine example of using Eleventy with Gulp and Sass. At time of writing, the zachleat.com source code is an older example that works with Grunt and Sass (not anymore though).

Quick Tip: Zero Maintenance Tag Pages for your Blog

2018-06-08T05:00:00Z

This quick tip will show you how to automatically generate Tag Pages (lists of content tagged into a collection).

We’ll use pagination to automatically generate a template for each tag we want to link to.

Here’s a sample pagination template using Nunjucks:

---
pagination:
  data: collections
  size: 1
  alias: tag
permalink: /tags/{{ tag }}/
---

<h1>Tagged “{{ tag }}”</h1>

<ol>
{% set taglist = collections[ tag ] %}
{% for post in taglist | reverse %}
  <li><a href="{{ post.url }}">{{ post.data.title }}</a></li>
{% endfor %}
</ol>

First up notice how we’re pointing our pagination to iterate over collections, which is an object keyed with tag names pointing to the collection of content containing that tag.

Consider these two sample markdown posts, one using a tech tag and one using a personal tag:

---
title: My First Post
tags:
  - tech
---

---
title: My Second Post
tags:
  - personal
---

Our pagination template above will now generate two pages: /tags/personal/index.html and /tags/tech/index.html.

The great thing here is that we don’t have to manage our tag list in a central place. These tags can be littered throughout our content and individual tag pages will be created automatically.

Filtering / Excluding

Have a tag you’d like to exclude from this list? Use pagination filtering like this:

---
pagination:
  data: collections
  size: 1
  alias: tag
  filter:
    - tech
permalink: /tags/{{ tag }}/
---

Now Eleventy will only generate a /tags/personal/ template and tech will be ignored.

In Practice

This is currently in use on the eleventy-base-blog sample project. Check out source code in the tags.njk template and see a live demo.

Quick Tip: Inline Minified JavaScript

2018-06-08T05:00:00Z

Originally posted on The Simplest Web Site That Could Possible Work Well on zachleat.com

This tip works great if you have small JS utilities that you’d like to have in your <head>. For example, this works great with the Filament Group loadJS or loadCSS utilities.

Installation

npm install terser to make the terser minifier available in your project.

Configuration

Add the following jsmin filter to your Eleventy Config file:

eleventy.config.js

ESM CommonJS

import { minify } from "terser";

export default function (eleventyConfig) {
	eleventyConfig.addFilter("jsmin", async function (code) {
		try {
			const minified = await minify(code);
			return minified.code;
		} catch (err) {
			console.error("Terser error: ", err);
			// Fail gracefully.
			return code;
		}
	});
};

const { minify } = require("terser");

module.exports = function (eleventyConfig) {
	eleventyConfig.addFilter("jsmin", async function (code) {
		try {
			const minified = await minify(code);
			return minified.code;
		} catch (err) {
			console.error("Terser error: ", err);
			// Fail gracefully.
			return code;
		}
	});
};

Create your JavaScript File

Add a sample JavaScript file to your _includes directory. Let’s call it sample.js.

// Hi
console.log("Hi");

Capture and Minify

Capture the JavaScript into a variable and run it through the filter (this sample is using Nunjucks syntax)

<!-- capture the JS content as a Nunjucks variable -->
{% set js %} {% include "sample.js" %} {% endset %}
<!-- feed it through our jsmin filter to minify -->
<script>
{{ js | jsmin | safe }}
</script>

Warning about Content Security Policy

WARNING

If you are using a Content Security Policy on your website, make sure the script-src directive allows 'unsafe-inline'. Otherwise, your inline Javascript will not load.

Quick Tip: Add Edit on GitHub Links to All Pages

2018-06-08T05:00:00Z

It’s nice to be able to instantly edit your HTML on GitHub when you spot an error or an improvement you can make. Why not facilitate this by adding an Edit this page on GitHub link to every page? You can see an example of this on our page footer.

Use a Layout File

Make sure you’re using a Layout file so that you can add these to a single place and have the links applied to all of your pages.

Read more about Layouts

Here’s a sample:

…
    <footer>
      © 2019 Eleventy
    </footer>
  </body>
</html>

Add your link!

Edit your layout file to add the link. Provide the URL to the base of your repo and use the Eleventy provided {{ page.inputPath }} variable to point to the correct input file. Yes, this will also work with paginated templates.

…
    <footer>
      © 2019 Eleventy
      <a href="https://github.com/11ty/11ty-website/blob/main/{{ page.inputPath }}">Edit this page on GitHub</a>
    </footer>
  </body>
</html>

That’s it!

Quick Tip: Inline Minified CSS

2018-06-07T05:00:00Z

Originally posted on The Simplest Web Site That Could Possibly Work Well on zachleat.com

This tip works well on small sites that don’t have a lot of CSS. Inlining your CSS removes an external request from your critical path and speeds up page rendering times! If your CSS file is small enough, this is a simplification/end-around for Critical CSS approaches.

Installation

npm install clean-css to make the CSS minifier available in your project.

Configuration

Add the following cssmin filter to your Eleventy Config file:

eleventy.config.js

ESM CommonJS

import CleanCSS from "clean-css";

export default function (eleventyConfig) {
	eleventyConfig.addFilter("cssmin", function (code) {
		return new CleanCSS({}).minify(code).styles;
	});
};

const CleanCSS = require("clean-css");

module.exports = function (eleventyConfig) {
	eleventyConfig.addFilter("cssmin", function (code) {
		return new CleanCSS({}).minify(code).styles;
	});
};

Create your CSS File

Add a sample CSS file to your _includes directory. Let’s call it sample.css.

body {
	font-family: fantasy;
}

Capture and Minify

Capture the CSS into a variable and run it through the filter (this sample is using Nunjucks syntax)

<!-- capture the CSS content as a Nunjucks variable -->
{% set css %} {% include "sample.css" %} {% endset %}
<!-- feed it through our cssmin filter to minify -->
<style>
	{{ css | cssmin | safe }}
</style>

Warning about Content Security Policy

WARNING

If you are using a Content Security Policy on your website, make sure the style-src directive allows 'unsafe-inline'. Otherwise, your inline CSS will not load.

Or: use an `11ty.js` Template

Contributed by Zach Green

You can also inline minified CSS in a JavaScript template. This technique does not use filters, and instead uses async functions:

eleventy.config.js

ESM CommonJS

import fs from "node:fs/promises";
import path from "node:path";
import CleanCSS from "clean-css";

export default async function (data) {
	return `<style>
	  ${await fs
			.readFile(path.resolve(__dirname, "./sample.css"))
			.then((data) => new CleanCSS().minify(data).styles)}
	</style>`;
};

const fs = require("node:fs/promises");
const path = require("node:path");
const CleanCSS = require("clean-css");

module.exports = async function (data) {
	return `<style>
	  ${await fs
			.readFile(path.resolve(__dirname, "./sample.css"))
			.then((data) => new CleanCSS().minify(data).styles)}
	</style>`;
};

Eleventy Quick Tips

Quick Tip: Draft Posts using Computed Data

Quick Tip: Use local plugins to reduce config file size

Quick Tip: Transform Global Data using an `eleventyComputed.js` Global Data File

Quick Tip: Cache Data Requests

Features

Example

Failing Even More Gracefully

Quick Tip: Trigger a Netlify Build Every Day

Step 1 Create a Build Hook

Step 2 Schedule the Hook Trigger

Mini-Tutorials

IFTTT

Quick Tip: Fetch GitHub Stargazers Count (and More) at Build Time

Get the Stargazers Count from the GitHub API

More Examples

Recommended: Cache the Data to the File System

Update Counts Daily

Quick Tip: Adding a 404 Not Found Page to your Static Site

.htaccess

With --serve

Quick Tip: Super Simple CSS Concatenation

Capture and Minify

Warning about Content Security Policy

Work with what you have

Quick Tip: Zero Maintenance Tag Pages for your Blog

Filtering / Excluding

In Practice

Quick Tip: Inline Minified JavaScript

Installation

Configuration

Create your JavaScript File

Capture and Minify

Warning about Content Security Policy

Quick Tip: Add Edit on GitHub Links to All Pages

Use a Layout File

Add your link!

Quick Tip: Inline Minified CSS

Installation

Configuration

Create your CSS File

Capture and Minify

Warning about Content Security Policy

Or: use an 11ty.js Template

With `--serve`

Or: use an `11ty.js` Template