11ty Rocks!

Smart Incremental Rebuilds With eleventyImport

2023-03-18T00:00:00Z

The Eleventy v2 release improved incremental builds in several ways.

However, a standing issue had been that when you display content from a collection and run an incremental build, that content wouldn't be updated in-sync. You would have to stop an restart your build, or opt back out of incremental local dev.

An additional method was added in v2 to resolve this behavior, and allow you to define which collections can re-build an associated template.

Using `eleventyImport`

The eleventyImport object can be added via front matter with one child parameter of collections that has an array value. The array should contain the names of any collections you process content from on the page.

The docs for this feature give a post collection as the example:

---
eleventyImport:
  collections: ["post"]
---
<ul>
{%- for post in collections.post -%}
  <li>{{ post.data.title }}</li>
{%- endfor -%}
</ul>

When will templates rebuild?

Any content change to a collection template will also trigger rebuild. The rebuild is only of the page that includes the eleventyImport object, and of the template where content was changed.

As noted on the incremental builds docs, rebuild also happens "when you add or delete a tag from a template, any templates using that collection tag... will be rebuilt."

That said, any way you create a collection makes the collection eligible to be included in eleventyImport.

Beware of circular imports

If your blog index resides in your posts folder and you are using a directory data file to assign the collection, then you'll want to exclude the main index from being included in collections:

eleventyExcludeFromCollections: true

Process CSS or Sass With LightningCSS

2023-02-25T00:00:00Z

To easily process CSS with Sass and/or LightningCSS, simply grab these plugins:

I've written a comparison of using Sass vs only LightningCSS if you're unsure which method you'd like to use.

If you want to learn how they work or how to more manually include these in your Eleventy build, read on!

Custom Template Languages in Eleventy

A powerful feature added in the Eleventy v1 release was the ability to add custom template extensions and template formats. Additionally, you can include a custom compile function.

This opens the possibility to extend processing during build to tools like Sass, or run additional processing against already recognized types like JavaScript such as to minify.

Or, as the docs show, you can even invent a file type in order to customize the output in some way.

We'll be taking advantage of this feature to add our custom processing of Sass or CSS files.

Adding Sass Support

The docs actually use Sass as the example for adding support, but here is the compiled snippet with the key features to include.

First, you'll need to install the sass package - npm install sass - and also include it in your config.

const sass = require("sass");

Then, the following should be placed within your config export:

// Recognize Sass as a "template languages"
eleventyConfig.addTemplateFormats("scss");

// Compile Sass
eleventyConfig.addExtension("scss", {
  outputFileExtension: "css",
  compile: async function (inputContent, inputPath) {
    // Skip files like _fileName.scss
    let parsed = path.parse(inputPath);
    if (parsed.name.startsWith("_")) {
      return;
    }

    // Run file content through Sass
    let result = sass.compileString(inputContent, {
      loadPaths: [parsed.dir || "."],
      sourceMap: false, // or true, your choice!
    });

    // Allow included files from @use or @import to
    // trigger rebuilds when using --incremental
    this.addDependencies(inputPath, result.loadedUrls);

    return async () => {
      return result.css;
    };
  },
});

Important: Exclude Custom Template Files from `all` Collection

At this time, any custom template files will end up in collections.all. This is very problematic if you are using that collection for things like sitemaps or RSS feeds.

Until Zach decides which way he wants to address this in core, the quickest fix is to create a directory data file to exclude your Sass (or other custom) files.

Place the following in the directory containing your Sass files. As an example, for a directory called css the file would be called css/css.json:

{
  "eleventyExcludeFromCollections": true
}

Autoprefixing and Minification with LightningCSS

If you are using more modern CSS features, you'll want to at least include prefixing. And for even more support of other upcoming features like nesting, color functions, media query range syntax I encourage using LightningCSS.

We can update the previous snippet to include LightningCSS so that we still support Sass processing.

First, install both lightningcss as well as browserslist.

npm install lightningcss browserslist

And include those in your config:

const browserslist = require("browserslist");
const { transform, browserslistToTargets } = require("lightningcss");

We've had to include both things so that we can pass browser compile targets to LightningCSS, otherwise prefixing and other transforms of modern CSS would not be applied. This handy web app will help you decide on your browserslist targets.

In our earlier Sass snippet, we'll update the final return section:

let targets = browserslistToTargets(browserslist("> 0.2% and not dead"));

return async () => {
  let { code } = await transform({
    code: Buffer.from(result.css),
    minify: true,
    sourceMap: false,
    targets,
  });
  return code;
};

Use the Eleventy plugin for Sass and LightningCSS to use this setup without adding all of this manually to your config.

Process with LightningCSS Only, No Sass

If Sass isn't something you want to use, then we can remove the Sass bits and only process our CSS with LightningCSS.

You'll still need to install the following:

npm install lightningcss browserslist

Then include them in your config:

const browserslist = require("browserslist");
const { bundle, browserslistToTargets, composeVisitors } = require("lightningcss");

And here's the full snippet to place in your config. This includes a preference to allow "bundling" which enables including other files via the @import syntax. The snippet also assumes those files are prefixed with _ which you can omit or change to your preference.

// Recognize CSS as a "template language"
eleventyConfig.addTemplateFormats("css");

// Process CSS with LightningCSS
eleventyConfig.addExtension("css", {
  outputFileExtension: "css",
  compile: async function (_inputContent, inputPath) {
    let parsed = path.parse(inputPath);
    if (parsed.name.startsWith("_")) {
      return;
    }

    let targets = browserslistToTargets(browserslist("> 0.2% and not dead"));

    return async () => {
      // Switch to the `transform` function if you don't
      // plan to use `@import` to merge files
      let { code } = await bundle({
        filename: inputPath,
        minify: true,
        sourceMap: false,
        targets,
        // Supports CSS nesting
        drafts: {
          nesting,
        },
      });
      return code;
    };
  },
});

Don't miss the step to exclude these files from collections.all discussed earlier.

A plugin to process CSS with LightningCSS only is also available.

Plugin or Manual Include?

The benefit of the plugin is that it will also automatically get your browserslist definition, and you can just drop it in across projects.

A manual include is great if you want to customize beyond what the plugins allow, or want to own the responsibility of updating the dependencies.

Plugin: Collection Schemas

2023-02-17T00:00:00Z

Enforce a typed frontmatter schema for templates within an Eleventy collection.

Define a unique schema per collection, then receive output during development and builds to note incorrectly typed, missing, invalid, or misplaced custom data keys.

Docs for Collection Schemas

Eleventy Collection Schemas

2023-02-17T00:00:00Z

A standout feature of Eleventy is the data cascade. This is the priority order of how global data, front matter data, and other data sources are computed for a given template.

Additionally, Eleventy allows the creation of collections of data. Often the reason for a collection is that the content has shared traits.

Let's consider a collection of blog posts, where your layout assumes availability of the following bits of data:

title
description
excerpt

None of these are going to be enforced or type-checked by Eleventy. But perhaps its important to you to make title and description required keys. Or in the future, you add a draft key that you want to ensure is a boolean, or an order field that should be a number.

Introducing: Collection Schemas

Collection Schemas is an Eleventy plugin that allows you to enforce a typed frontmatter schema for templates within an Eleventy collection. It works by you defining a unique schema per collection, then providing output during development and builds to note incorrectly typed, missing, invalid, or misplaced custom data keys.

Terminal output example shown in VS Code using the theme Apollo Midnight

Conditions evaluted for include:

Missing required meta keys: [LIST]
Possibly misplaced meta keys: [LIST]
Incorrect type for meta [KEY], change to [TYPE]
Invalid meta keys: [LIST]

Where "invalid" catches typos or extra, untyped keys that may need to be added to the schema.

How collection schemas work

The plugin introduces a new file extension of .meta (which is configurable) to design your schema with JSON. So for our blog post example, you might have the schema of:

{
  "title": {
    "type": "string",
    "required": true
  },
  "description": {
    "type": "string",
    "required": true
  },
  "excerpt": {
    "type": "string",
    "required": false
  }
}

This .meta file slots into the data cascade similar to a directory data file, so it will need the same name as the parent directory of your collection. To associate the schema with the collection, the collection will also need the same name.

posts/
  posts.meta
  posts.json
  post-one.md <- content in any templating language

Where posts.json is a directory data file that creates the collection via the tags mechanism:

{
  "tags": "posts"
}

✨ Tip: You can also use the directory data file to change the permalink for all templates in a collection if you don't want them to have the collection name as the URL base.

The plugin leverages the filter capability to obtain the page's total computed data, which will include the schema from the .meta file, and then will log any issues to the console.

To finish tying the schema to the collection via the filter, you'll also need to create a global data file called eleventyComputed.js (or extend an existing one) to include the following:

module.exports = {
  metaSchema: function (data) {
    return this.metaSchema(data);
  },
};

Review all the installation and configuration options for the plugin.

Then, nest any of your schema-related keys under the meta key within template front matter:

---
meta:
  title: "My Page Title"
  description: "One morning, when Gregor Samsa woke from troubled dreams, he found himself transformed in his bed into a horrible vermin."
---

Schema Limitations

Only one level of schema data is currently possible
Only the top-level collection is used to locate schemas

Plugin: Sass + LightningCSS

2023-02-02T00:00:00Z

Compile Sass in Eleventy (11ty) and process it with LightningCSS to minify, prefix, and add future CSS support.

Also respects either your package.json browserslist or a .browserslistrc, otherwise the default targets are > 0.2% and not dead.

Requires Eleventy v2 beta or stable.

Add Sass to 11ty

11ty Membership Site

2023-01-26T00:00:00Z

An Eleventy theme for offering premium content to members by using Edge-powered authentication. Requires Supabase and Netlify accounts.

Review this article on the high-level membership theme concepts to learn how members-only content works.

Get this theme

Building A Membership Site With 11ty

2023-01-26T00:00:00Z

Spoiler: This is available as an Eleventy theme over on GitHub. Read on to explore key concepts about developing using Eleventy Edge.

A new feature with Eleventy v2 (currently in beta) is Eleventy Edge.

What is "the Edge?" Here's a super brief summary:

Low-latency nodes geographically close to the user
- Faster processing of Edge functions vs. serverless
- Retrieve user-specific data, ex. timezone, cookies
“Middleware” to intercept page requests before they are rendered
Allow redirecting or modifying requested content

These features allow us to enable authenticated routes for our 11ty site. And the opt-in Eleventy Edge plugin enables us to add and use Edge-generated data within otherwise static 11ty templates.

Prerequisites

11ty v2 beta+ (included in the membership theme)
Netlify account
Netlify CLI
Supabase account

Additionally, opting-in to the Eleventy Edge plugin. This is not a separate install, but it is not included in your build by default. The following are the parts to include (if you are not using the theme).

const { EleventyEdgePlugin } = require("@11ty/eleventy");

module.exports = function (eleventyConfig) {
  // Opt-in to 11ty Edge
  eleventyConfig.addPlugin(EleventyEdgePlugin);
};

How it works

Supabase out-of-the-box has user sigups enabled, and from that we can setup "magic link" authentication as a starting point. This means a new or returning user enters their email and Supabase sends an email with a one-time access token. It's then up to our site for how to handle the user's journey after they return with that token.

For our minimum-viable membership site, here are the features:

Authenticate users with Supabase Magic Links and provide members-only content
Offer partial content previews to unauthenticated users
Build using 11ty, Netlify Edge, and Supabase
Use no frameworks or bundlers, just vanilla JS (+ Deno on the Edge), Nunjucks, and Markdown

So, how does this come together? First, Supabase offers an API and functions to easily trigger the necessary actions like login, and retrieval of a user's session details.

With the Netlify CLI, we have access to environment variables stored in our Netlify account so that those can be shared to local dev. The Netlify CLI also enables actually using the Edge functions for local development.

With Edge + Supabase, we don't need a single-page application framework because only a couple of tiny JavaScript functions are required client-side for initial login! We'll create a cookie on the Edge to store an _access_token based on Supabase session details to use for subsequent page requests.

Eleventy Edge then is attached to each page load where we check for the _access_token cookie and use the value to validate a user. Edge checks the user's status before they see any page content and sends down an isUser variable to pick up in our 11ty templates. Within the {% edge %} shortcode provided by the plugin is where we render the members-only content, or prompt for a login.

The rest is leveraging the Nunjucks templating language, and also using Markdown as the way to author post content.

Authentication Flow

User enters email and triggers magic link login from either the index or a post
Supabase auth sends a magic link to user's email
User returns through magic link and arrives at /session/ where:
- Supabase saves session data to localStorage
- session.js picks up the session variables and redirects to /access/
/access/ route loads the netlify/edge-functions/login.js Edge function which saves the _access_token cookie*
User redirected to the login-originating page (either the index or a specific post)

* Why a cookie? Edge functions can read cookies from page headers, so it's used to validate sessions across page loads.

Assigning routes to Edge functions

Netlify Edge looks at the netlify.toml file to determine when to pass a page request through an Edge Function.

Here's the example of setting the route for the login Edge function:

[[edge_functions]]
path = "/access/*"
function = "login"

Members-Only Content Flow

The author determines which content (if any) will be gated by setting the premium variable
When a user visits a gated post, the 11ty Edge function (netlify/edge-functions/eleventy-edge.js) checks their authenticated status with Supabase, and sets isUser as global data for access within the {% edge %} shortcode
- If isUser: true - user sees the premium content
- If isUser: false - user sees partial content and the login form

The isUser variable is made available because Eleventy Edge allows creating global data on-the-fly! With one caveat: it's exclusive to the edge shortcode and only on routes covered by the Edge function. In other words, it is dynamic and isolated to that page load, and does not become a part of the static 11ty build.

Authoring premium content

How does it look to set the premium variable? Here's an example post which is written in Markdown and uses Nunjucks for assigning the variable.

Example post content outside of the gated, members-only content.

{% set premium %}

This content is super premium! For members only!!

{% endset %}

{% include "components/gate.njk" %}

We then include a Nunjucks partial gate.njk after setting the premium variable which includes the {% edge %} shortcode and determines whether the user can see the premium content.

Note: We have to place the include alongside the content template rathen than in the layout used by the post because the premium variable will not be available to a layout. So, the include must be added by authors on each post with members-only content.

{# gate.njk #}

{% set loginform %}
{% set loginHeadline = "To continue reading, join or login" %}
{% include "components/loginform.njk" %}
{% endset %}

{% edge "njk, md", { premium: premium, loginform: loginform } %}
  {% if premium %}
    {% if isUser %}
      {{ premium }}
    {% else %}
      {{ loginform | safe }}
    {% endif %}
  {% endif %}
{% endedge %}

For the shortcode, we also designate which templating languages it should use to process the content: Nunjucks njk and Markdown md. We need Markdown so that it transforms the authored post content within the premium variable.

An important concept is that Eleventy Edge is not aware of data from your 11ty site so it must be explicitly passed into the shortcode. That's why we must set the loginform include as a variable as well. Additionally, in order to have named variables within the shortcode, we have to pass them in as an object (but remember: this is Nunjucks, not JS!).

Finally, the logic within the shortcode says: "If there is premium content and also a valid user, we can show them the content. Otherwise, show the login form instead."

Next steps and resources

There are several opportunities for enhancements from the starter theme.

Create a user dashboard
Persist user profile data to Supabase
Add in payment processing
Use WebC to save content bookmarks or perform other client-side interactions

Here are resources to help understand each of the necessary parts more in-depth, and learn how to extend the functionality:

Learn more about all kinds of 11ty topics here on 11ty Rocks!
11ty Edge docs
Supabase authentication docs
Netlify Edge docs

11ty Community Links: January 2023

2023-01-21T00:00:00Z

Chris Coleman - “Using Eleventy filters in Directory Computed Data” - shows how a switch to using 11tydata.js instead of JSON for data directory files allows regular JS and therefore more complex logic to work out assigning values for computed data.
Benny Powers - “SVG Icon Sprites in Eleventy” - uses a technique of creating a collection out of a directory of SVG icons and programmatically turning those into an SVG sprite, and a clever way to add the sprite only once per page where at least one of the associated shortcodes is used.
Vadim Makeev - “CSS and JavaScript as first-class citizens in Eleventy” - shows how to use the v2 additions of addTemplateFormats and addExtension to process CSS and JS.
David Darnes - “Compile JavasScript and Sass in Eleventy using Uglify JS and Sass lib” - is a gist that gives a little different take from Vadim’s article but using the same 11ty features.
Christopher Kirk-Nielsen - “Eleventy Asset Pipeline: Precompiled Assets without Gulp” - demonstrates an alternative to the previous two articles with the use of eleventy.before as well as addressing a bit different goals.
Ashur Cabrera - “Importing external components in WebC via NPM” - explores using webc:import to share WebC components between projects.
Lene Saile - “Organizing the Eleventy config file” - provides some excellent considerations and techniques for taming your 11ty configuration setup.
Also from Lene - “Eleventy Excellent” - looks like a truly excellent starter to get an 11ty site going quickly!
Eleventy Blog / Zach Leatherman - “The very first beta release of Eleventy v2.0” - the official announcement of the v2 Beta!
11ty Rocks / Stephanie Eckles - “New Features and Upgrade Considerations for Eleventy v2.0.0” - provides a little more context on the major feature additions, breaking changes, and various enhancements to help you prepare for v2.
Bryan Robinson - “11ty Second 11ty” - a YouTube series where Bryan shows off features of Eleventy in snack-size videos.

Add your own original article on a unique 11ty topic to the 11ty Rocks Community Resource page!

New Features and Upgrade Considerations for Eleventy v2.0.0

2023-01-12T00:00:00Z

2.0.0 canaries have been available for quite some time, and creator Zach Leatherman has helpfully been updating the docs by adding labels to note when a feature became available.

The 2.0.0 release is available as of February 8, 2023, which includes the changes noted in this article.

Recently, I set out to create a new Eleventy project for the first time in a few months using the latest Canary and hit some unexpected errors. That led me down the rabbit hole to see what exactly had changed so I could be prepared to update projects, especially as I use similar setups cross-project and maintain a few 11ty starters.

This may not be 100% comprehensive, but it includes the most impactful highlights for general use of 11ty.

If it’s been a while since you created or updated an Eleventy project, you may want to glance at the last section for features you might have missed from v1.0.0.

Major Feature Additions

Eleventy Edge

Currently only available for projects run on Netlify, this exciting addition brings a shortcode that allows dynamic content to be added to your projects on the edge. What’s that, you say? It means you can modify a page request before the page content is sent to the user, which allows getting data like the user’s timezone. It also enables retrieving cookies to check if the user is authenticated and permitted to access a particular route. Or, it offers the chance to set cookies to persist preferences like a color theme. These ideas are just the beginning of what’s possible with Eleventy Edge!

Join me on January 25 and 26 for TheJam.dev where I’ll demonstrate using Eleventy Edge to build a membership site on Eleventy.

WebC

In line with moves made by other site builders, WebC offers the ability for single-file web components. Really what that means is WebC is a first-class templating language in Eleventy that you can use to render “real” web components or as an alternative to solutions like Nunjucks includes and macros for reusable components in your 11ty site.

Check out these posts from 11ty Rocks to learn more about WebC use cases and features:

Breaking Changes

A few changes as noted in the release notes, which Zach recommends using the eleventy-upgrade-helper plugin to discover whether your site is impacted.

Update from an earlier version of this post: a proposed breaking change to addPassthroughCopy was reversed.

Configuration, Build, and Serve

First up, there are now new options for naming your Eleventy config file.

.eleventy.js - only option < v2.0.0-canary.15
eleventy.config.js - coming in v2
eleventy.config.cjs - coming in v2

The default Eleventy dev server is now a custom solution instead of BrowserSync. If you have customizations reliant on BrowserSync, you can revert back with a config option. However, the default server is much faster and lighter and doesn’t require loading any JS during watch and serve local dev.

If your site benefits from programmatic ignores (like separating dev vs. prod environment files), you may be interested to know that --watch ignores are now available separately.

Various enhancements landed for incremental builds, notably:

Layouts - a change rebuilds any templates using that layout
Collections - adding or deleting a tag from a template will rebuild any related templates

To make local dev even faster, you may wish to opt-in to emulated passthrough file copying for faster local builds. Note that opting-in may have breaking behavior if you are copying through files that other processes depend on. For instance, maybe you are referencing a file for your serverless build or a plugin requires a precise and real file path from your final output. In that case, simply do not opt-in to this feature.

A new command line flag of --ignore-initial will run Eleventy without an initial build.

The configuration events added in v1 will have event arguments available in v2 that provide metadata about the build, including the following objects:

dir - object with current project directories
outputMode - default is fs (file system), or option passed via —to
runMode - one of build, watch, or serve
results - for eleventy.after only, includes processed Eleventy output

Finally, for configuration updates, if you don’t want directory indexes created by default, you can change your default permalinks with this snippet.

Custom Data and Data Cascade

The supplied data variables of eleventy (added in v1) and page will be available as of v2 in filters and shortcodes. The page variable has also been extended to transforms, linters, and collection entries.

I’m a big fan of directory data files (here are some tips for using them). In v2, you can configure a different base file name for them instead of the default of matching them to the directory file name, ex. index.

Custom data formats (the ability to support additional template extensions) received various updates.

A late addition for Eleventy Serverless (introduced v1) added the ability to compile the data cascade. This means access to collections without extra hoops to make them available to serverless templates (with caveats noted in docs).

Collections, Filters, and Shortcodes

An exciting update for those of us who have tried to get dynamic/real-time data pulled at build-time is universal async shortcodes and universal async filters!

Collections received a couple of updates, including:

declaring collections for incremental builds to trigger rebuilds when a collection item is changed
new/updated data structure for collection items, notably:
- Use page.url instead of url (see docs for other properties moved to page)
- Use content instead of data.templateContent to get the compiled output

You can now chain ‘log’ in filters, for example {{ myData | log | otherFilter }}. Whereas before, you would have to break those calls apart, now log will output and then pass the data along the chain to the next filter.

Content Creation

Here are some quick hits that may impact how you create content with Eleventy:

new date option: git Created
pagination option to allow empty pages when no data is available
map one URL to multiple files, useful for scenarios like internationalization
Markdown processing by default now has disabled indented code blocks

Also, when defining layout files, it is now strongly recommended to include the layout file extension. This is due to the slowness of determining which file is actually meant to be used when no extension is included.

---
layout: base <- no longer recommended
layout: base.njk <- best practice: always add file extension
---

Upgrading to v2.0.0

The top two things that may impact your current projects are:

changing collection data references like url to be based off of page and updating templateContent to content
including the file extension when you define a layout, ex layout: base.njk instead of layout: base

And, perhaps you may want to change the name of your Eleventy config.

There's also an upgrade plugin available: eleventy-upgrade-help

What You Missed From v1.0.0

I started using Eleventy at version 0.10.0 in April 2020, and v1.0.0 stable was released a year and a half later, on January 9, 2022. If you also did most of your learning with Eleventy before v1 and haven’t updated things or built new in a while, there’s a good chance you missed some of the following!

Probably the biggest feature splash was Eleventy Serverless, which enables building entire templates upon page request for fully dynamic pages. The two available modes are:

On-demand builders which cache the result after the first page request (rebuild to expire), great for infrequently used pages or generating open graph images
Dynamic templates which re-render on every page request, great for CMS previews, accepting user input, or even to generate and display site search results

Here are several other key updates from Eleventy v1.0.0:

slug filter changed to slugify with better special character handling
Date formats are assumed to be UTC
Noted earlier, but configuration events to run code before or after compile
Data deep merge on by default resulting in data like tags that are added in a template and a layout being merged together, rather than the template, which has higher data cascade priority, having only its tags used
Speaking of the data cascade, the priority of front matter data in layouts was lowered
Global data was allowed to be added from the config file
Custom template extensions allow adding your own template formats and provide a custom compiler, such as the docs example of adding Sass processing
The render plugin enables shortcodes to render template strings or files inside of a template of a different template language, ex. render a Markdown block within Nunjucks

Whew, that was a lot! Go forth and enjoy building with these new and updated Eleventy features! PS - if you're new to Eleventy, check out my guide to creating your first basic 11ty website.

Understanding WebC Features and Concepts

2022-10-24T00:00:00Z

If you haven’t yet heard of WebC, check out another 11ty Rocks article, Introduction to WebC.

Including WebC components outside of `.webc` templates

One option for using WebC is to go all in and start defining your templates using the .webc extension. If you do that, you’ll also get access to any components you define due to already being within a WebC context.

For myself, I want to use my WebC components within other templates that I already have. Typically, I favor Nunjucks and Markdown for my 11ty projects.

One way to make WebC components available to other template types is by listing the path under the components option for the WebC plugin (aka “global no-import components”). The gotcha here is when you have also customized your 11ty input directory to something besides the default of the project root.

The components path is root-relative as opposed to input directory relative, which means that if you customize the input directory, you’ll need to include that in the path update.

I like to customize the input directory to src, which makes the following my path when following the recommendation to put the components directory inside the _includes directory.

eleventyConfig.addPlugin(pluginWebc, {
  components: "src/_includes/components/**/*.webc",
});

Extra gotcha: If you try to place your components directory outside the _includes directory, you’ll have to resolve ignoring it during 11ty’s build process, which is already handled if you stick with placing it in _includes. Otherwise, your components will build out as extra pages which is not the behavior you want!

You’ll also need to include the Render plugin to process your WebC components outside of .webc templates, which supports Liquid, Nunjucks, and 11ty.js.

The Render plugin is included with 11ty but is opt-in, so here are the changes to make to your config:

// .eleventy.js
const { EleventyRenderPlugin } = require("@11ty/eleventy");

// Add the plugin within your existing module export
module.exports = function (eleventyConfig) {
  eleventyConfig.addPlugin(EleventyRenderPlugin);
};

Then you can use the Render plugin to wrap your WebC component when outside of a .webc template.

// Nunjucks
{% renderTemplate "webc" %}
<my-custom-component></my-custom-component>
{% endrenderTemplate %}

Unfortunately, using the Render plugin to try to render your WebC components in markdown will not be successful. I’ve created an issue to hopefully work this out for folks like myself who write blog posts with markdown.

Static HTML WebC rendering vs. web component rendering

Since WebC is very new, a misconception I had was that it created “real” web components in all instances. As it turns out, using WebC for native web component rendering is not the primary concern and entirely up to you as the author.

WebC for static HTML

WebC promotes the use of static HTML and can be used as a way to include HTML that has awareness of the Eleventy data cascade. This makes WebC an alternative to methods like Nunjucks includes or macros, or Eleventy shortcodes.

When using WebC for static HTML components, the outer wrapper - for example, <my-component> - is removed in the final rendering.

Once you include a style or script block in your WebC component, it is treated as a custom element. By default the outer wrapper - aka the “host component” - is retained, which is the first difference from HTML-only WebC components. A unique aspect of how WebC handles this rendering is that you can overload any existing element, such as blockquote or img.

If you’re interested in how WebC handles scripts and styles, learn about WebC asset bundling in the docs.

Up until the point you register a web component, you still have a static HTML WebC component. This means you can still leverage scoped styles and co-locate your scripts and take advantage of the WebC format without the jump to a "real" web component.

WebC for web components

So, what if you want a real web component? If you have low experience with creating them, a gotcha may be that in order to register a native web component, it needs to have a hyphenated name like super-slider and not just slider.

You’ll also need to ensure that when you place the script tag for the asset bundle that it includes the attribute type="module" or the browser will prevent it registering correctly.

It should be noted that WebC becomes the manager for scripts and styles but the native web component behavior described doesn’t strictly require WebC.

11ty’s creator, Zach Leatherman, is positioning WebC as a convenience for building progressively enhanced components that work when Javascript is not available. One method that may be appropriate if your component relies on JS to work is to wrap your WebC content with the native HTML template element. This will prevent the contents rendering immediately to the page. Then, by registering your web component, which happens with JS, you can reveal the template contents.

Evan shows this pattern of using template in the theme-select example from the 11ty Rocks’ article Introduction to WebC.

We'll review a bit more advanced use of template in the last section.

Styling for custom elements and web components

It may surprise you (as it did me!) to see that styles are applied to custom elements without a shadow DOM. This includes affecting what renders after the template content becomes visible using the method described.

You can use two native CSS selectors to distinguish between the states of before and after the component is registered, which is especially useful if not all your component elements are wrapped up in template.

:host - refers to the parent custom element/web component
:host:defined - the “defined” state is true after a web component is registered, which effectively also means when JS is available

For general use of :host outside of a shadow DOM, within WebC you’ll also need to set webc:scoped on style. WebC will then hijack :host to generate a hashed class for “scoping” the styles you define to your custom element.

This WebC concept means you can use :host when you’ve defined a custom element that isn’t registered to become a web component to benefit from scoping.

Alternatively, you can apply classes within your .webc component or per instance and use styles from your stylesheet and any framework. WebC will merge classes as necessary and will apply the classes to the outer custom element.

Data within WebC components

There are three main ways to render data passed into your WebC component:

@html allows rendering the attribute as the HTML content
dynamic attributes are created be prepending an HTML attribute with a colon, like :att and filling it with the corresponding attribute from the host component
slots, which we’ll discuss in the next section

Both @html and dynamic attributes allow rendering of attributes/props passed to the host component. The following shows how to use each for a form field component.

<!-- page.webc -->
<form-field label="Name" type="text" value="Stephanie"></form-field>

<!-- form-field.webc -->
<label @html="label"></label>
<input :type="type" :value="value" />

Unique values using `uid`

An (as yet) undocumented feature of the WebC plugin is the attribute uid which generates a unique string per instance. We can use this to enhance our form-field component to ensure each field has a unique id and semantically using that as the value of the label for as well.

<!-- form-field.webc -->
<label @html="label" :for="uid"></label>
<input :type="type" :value="value" :id="uid" />

<!-- renders to: -->
<label for="webc-97Lq2">Name</label>
<input type="text" value="Stephanie" id="webc-97Lq2" />

Concatenating strings

Keeping with our form-field, perhaps we want to enable a field description. For accessibility we should tie that to the field with aria-describedby. We can concatenate an extra string with the uid to create the id for that relationship:

<input :type="type" :value="value" :id="uid" :aria-describedby="'desc-' + uid" />
<p :id="'desc-' + uid" @html="description"></p>

This JS-flavored syntax for concatenating works for any dynamic attribute, as well as populating the @html value. Alternatively, you can use template literal strings, such as :id="`desc-${uid}`".

Privatising attributes

So far, this example is static HTML so WebC strips the custom element from the final render. If we add some scoped style, the custom element is retained. Additionally, the attributes we passed in are also retained as attributes on the custom element and are visible in the browser:

<!-- rendered source -->
<form-field
  label="Name"
  type="text"
  value="Stephanie"
  description="Your first name please"
  class="wjuym-vnb"
></form-field>

To remove those from continuing to be part of the custom element, with WebC we can make them “private” when including the component. This is done by prepending each attribute with @, such as @label, which turns it into a property (aka prop). In our form-field example, this means all attributes will be removed from the final render except the class.

Removing unnecessary elements

If we consider a secondary component for radios and checkboxes, maybe we want the label to wrap the input. This poses what may seem like a problem in that we need to still render the label value, which we’ve learned is done via @html and means we need to add an element to attach that too. You might be inclined to use a span as follows:

<label :for="uid">
  <input :type="type" :id="uid" />
  <span @html="label"></span>
</label>

A span is semantically ok, but if you do not need it for styling purposes, then you can attach the attribute webc:nokeep which will discard the span upon render.

Since you’re discarding the element, you can choose something else even completely made-up as long as you haven’t assigned it to another WebC component. For example, simply x:

<x @html="label" webc:nokeep></x>

Advanced patterns with slots

Attributes and props fit a lot of use cases, but to enable a bit more flexibility in structuring your components you can use slots. Evan already covered using slots for a static HTML card component in the intro article, so we’ll look at two other patterns.

First, we can break up large components and use slots to fit them together thanks to WebC rendering.

If we create a form-submit component separate from the form-field and form-input then we can use slots to help structure the component. We’ll have a single slot called fields which can be populated per instance. This allows freeform flexibility for how the form fields are created and ordered.

<!-- form-submit.webc -->
<form>
  <slot name="fields"></slot>
  <button type="submit">Submit</button>
</form>

<!-- turn it into a full web component to handle validation
and submission logic -->

Then, we assign to fields to the slot by referencing the name of fields in the slot attribute. Also note the use of webc:nokeep which is optional but may be preferred.

<!-- page.webc -->
<form-submit>
  <div slot="fields" webc:nokeep>
    <form-field label="Name" type="text" value="Stephanie" description="Your first name please"></form-field>

    <fieldset>
      <form-input label="Blue" type="radio" name="fav-color"></form-input>
      <form-input label="Red" type="radio" name="fav-color"></form-input>
      <form-input label="Green" type="radio" name="fav-color"></form-input>
    </fieldset>
  </div>
</form-submit>

The result is that WebC will statically render the individual fields within the form.

If your form requires JS, like a POST request to submit a newsletter form, then you may want to introduce the template pattern. Let’s setup up a form that also uses slots to represent optional fields. A neat feature of slots is if they are not given content, they are removed from rendering.

<!-- subscription-form.webc -->
<template>
  <form>
    <slot name="name"></slot>
    <slot name="email"></slot>
    <slot name="business"></slot>
  </form>
</template>

<script>
  class SubscriptionForm extends HTMLElement {
    connectedCallback() {
      const template = this.querySelector("template");

      // Swap out the template with its contents so they become visible
      template.replaceWith(template.content);
    }
  }

  window.customElements.define("subscription-form", SubscriptionForm);
</script>

And then to use it, we’ll reference our <form-field> component and directly assign those to a slot:

<!-- page.webc -->
<subscription-form>
  <form-field slot="name" @label="Name" @type="text"></form-field>
  <form-field slot="email" @label="Email" @type="email"></form-field>
</subscription-form>

Note that we can’t make slot a private prop with @ or it will fail to be assigned, so you will still see this attribute on the final render.

But - oh no! The slots haven’t been passed along correctly and aren’t rendering in the browser:

<!-- rendered source -->
<subscription-form>
  <template>
    <form>
      <slot name="name"></slot>
      <slot name="email"></slot>
      <slot name="business"></slot>
    </form>
  </template>
</subscription-form>

When you try to use slots within template, and your intent is to allow WebC to process those for rendering, you’ll need a couple extra attributes on template. Otherwise, WebC will default to keeping the slots exposed for client-side things within your web component.

The adjustments are to add both webc:keep and webc:type="11ty" to the template. Use of webc:type="11ty" indicates that WebC should process the slots. And typically that would also wipe away the template so we need webc:keep added to keep it for the web component registration script.

<!-- adjustment in subscription-form.webc-->
<template webc:keep webc:type="11ty"></template>

Now the subscription-form not only renders but there is no error from not including the “business” slot, and no empty placeholder for it either:

<!-- updated rendered source -->
<subscription-form>
  <template>
    <form>
      <form-field slot="name" class="wjuym-vnb"> ... </form-field>
      <form-field slot="email" class="wjuym-vnb"> ... </form-field>
    </form>
  </template>
</subscription-form>

The composable nature of slots and how they can be processed at build-time rather than another piece for the client-side to handle makes this a strong contender against other Eleventy component patterns!

Have you created a WebC resource? Be sure to add it to the community resources or the 11ty Rocks webring!

Introduction to WebC

2022-10-15T00:00:00Z

WebC is a new tool by Zach Leatherman (creator of Eleventy) for serializing custom elements at build time. It aggregates component-level CSS and JavaScript, allowing developers to keep their styles and scripts together with the markup as single file components, the way you may be used to if you work with JavaScript frameworks such as Svelte or Vue.

All without having to ship a single line of JavaScript to the client — unless you want it to.

WebC in a nutshell

First and foremost: WebC components are just HTML. If you already know how to write HTML, CSS, and JavaScript, you are ready to start working with WebC.

Let’s define our first component: a footer for our site. We’ll create a file called site-footer.webc and put in it the following HTML:

<!-- site-footer.webc -->
<footer>
  <p>&copy; 2022 Yours Truly</p>
</footer>

Now we can use a <site-footer></site-footer> custom element and WebC will replace that element with the markup from site-footer.webc.

For the purposes of this article, we won’t concern ourselves with importing components in WebC. When you set up the WebC plugin for Eleventy, you can configure a directory for global components so that they’re always available.

So if we have a file — page.webc — with all of our HTML boilerplate, we insert our footer into that file using this custom element.

<!-- page.webc -->
<!doctype html>
<html>
  <head></head>
  <body>
    <site-footer></site-footer>
  </body>
</html>

When we process page.webc, the resulting HTML will look like this (give or take some whitespace):

<!-- page/index.html -->
<!doctype html>
<html>
  <head></head>
  <body>
    <!-- <site-footer> -->
    <footer>
      <p>&copy; 2022 Yours Truly</p>
    </footer>
    <!-- </site-footer> -->
  </body>
</html>

Single file components

At this point, it may still be unclear what advantages we get by using WebC. After all, many of the template languages that Eleventy already supports allow you to import partials from other files like this. But what WebC can add to even this basic use case is the single file component (SFC) authoring experience.

An SFC is a file that contains HTML, CSS, and JavaScript that defines the component. They often follow this structure:

<script></script>

<!-- Markup here -->

<style></style>

Going back to our site-footer.webc, we can colocate the styles for our footer with the markup.

<!-- site-footer.webc -->
<footer>
  <p>&copy; 2022 Yours Truly</p>
</footer>

<style>
  footer {
    padding-block: 3rem;
    padding-inline: 1rem;
  }

  footer > p {
    font-family: fantasy;
  }
</style>

One advantage to writing your components this way instead of having your markup and styles in separate files is that when you’re making changes, it’s easier to remember to update the styles. If we introduce a <div> to our footer to wrap the paragraph at some maximum width, our (admittedly contrived) footer > p selector will no longer apply to the copyright notice in the footer. Being able to see the markup and styles right next to each other helps us keep them synchronized.

Custom elements in WebC output

When you have a component that is just HTML, WebC will replace the custom element with that HTML. But as soon as you introduce either a <script> tag or a <style> tag to the component, WebC will, by default, leave the custom element in place in case you are using it in either your scripts or your styles. You can tell WebC to remove the custom element by adding webc:nokeep to the custom element.

Asset bundling

When WebC processes your components and it finds <style> or <script> tags in them, it can extract those assets into bundles for you to use later. This allows you to collect your assets into a single <style> tag inside the page <head>, rather than leaving <style> tags strewn about your HTML. See the Eleventy docs on WebC for information on how to include bundled assets in your final markup.

By default, when using the Eleventy plugin for WebC, asset bundling is turned on. If you are using WebC directly, however, bundling is off by default.

Scoped styles

One concern you may have about this single file component approach is that the styles from one component may leak into another. In our site-footer.webc component, for example, we have styles that apply to all <footer> elements; if we use a <footer> in any other part of our site, it will pick up that padding.

A common solution to this problem with SFCs is to scope the styles using some computer-generated unique class name. WebC supports scoped styles via the webc:scoped attribute, which you add to your <style> tag.

To scope our footer styles to just the <site-footer> element, we can update our component definition like this:

<style webc:scoped>
  :host {
    padding-block: 3rem;
    padding-inline: 1rem;
  }

  :host footer > p {
    font-family: fantasy;
  }
</style>

Did you know: :host is a native CSS feature that selects the shadow DOM root host of web components. WebC is using :host as a hook to insert the generated class name for scoped styles. If you use :host outside of scoped styles, it won’t be replaced, but it will still be valid CSS.

Here we’ve added the webc:scoped attribute to our <style> element, and introduced the :host pseudo-class to our selectors. WebC now knows to generate a unique class for <site-footer>, which will replace :host with a class selector matching this generated class name. The generated class will be shared across <site-footer> instances. So our HTML will end up looking something like:

<site-footer class="blarglargl">
  <footer>
    <p>&copy; 2022 Yours Truly</p>
  </footer>
</site-footer>

And the styles will be:

.blarglargl {
  padding-block: 3rem;
  padding-inline: 1rem;
}

.blarglargl footer > p {
  font-family: fantasy;
}

Slots

WebC supports the use of <slot></slot> for inserting markup inside your components when they’re used. And as with templates and slots for web components, you can define multiple named slots; something that none of the template languages Eleventy currently supports can do.

To illustrate how this can be useful, let’s create a card component that needs to have a title, some media, and a brief description. We won’t concern ourselves with the CSS for this component, but let’s assume we’re doing some fancy things that require us to place the aformentione title, media, and description inside some wrappers. We can define a-card.webc like this:

<!-- a-card.webc -->
<article class="card">
  <div class="card__container">
    <div class="card__media">
      <!-- Media will be inserted here -->
      <slot name="media"></slot>
    </div>
    <strong class="card__title">
      <!-- Title will be inserted here -->
      <slot name="title"></slot>
    </strong>
    <div class="card__body">
      <!-- Description will be inserted here -->
      <slot name="body"></slot>
    </div>
  </div>
</article>

When we use this card in our markup we place the title, media, and description as children of our custom element and give them the appropriate slot attribute.

<a-card>
  <a href="#" slot="title">The Hypnotoad</a>
  <img src="hypnotoad.gif" slot="media">
  <p slot="body">All glory to the Hypnotoad~</p>
</a-card>

Notice that we can order our elements however we want. We don’t have to place the media above the title when we define the card, because they will get pulled into the appropriate order when they're slotted into the component.

Did you know: Slots are also a native part of the web platform. You can use them along with <template> to achieve the same effect we get with WebC but in the browser — though, unlike with WebC, using templates and slots in the browser requires JavaScript. To learn more about templates and slots, check out Mozilla Developer Network’s article on using templates and slots.

WebC for web components

Up to this point, we’ve been looking at how we can use WebC in Eleventy for the same kinds of tasks for which we’ve previously used one of Eleventy’s template languages. But the WebC README declares (emphasis mine):

WebC is for Single File Web Components

So what does all of this have to do with web components? Well, we can use WebC single file components as a convenient way to write and include web components — with templates and shadow DOM — in our sites. As a simple example, suppose we want to implement a theme toggle on our site that allows visitors to choose a light or dark theme, or to use whichever matches their operating system. We’re implementing this as a web component because it relies on JavaScript to switch the theme. Without JavaScript, the buttons wouldn’t do anything, so we don’t want them to be visible unless JavaScript is available.

We’ll call our component theme-select.webc:

<!-- theme-select.webc -->
<script>
  class ThemeSelect extends HTMLElement {
    connectedCallback() {
      const template = this.querySelector("template");

      // Swap out the template with its contents so they become visible
      template.replaceWith(template.content);
    }
  }

  customElements.define("theme-select", ThemeSelect);
</script>

<template>
  <button>Light</button>
  <button>System</button>
  <button>Dark</button>
</template>

<style>
  theme-select {
    /* ... */
  }
</style>

The connectedCallback method is one of the lifecycle callbacks for custom elements. It runs whenever the element is connected to a document by appending it to another element in the document. You can learn more about these lifecycle callbacks and creating custom elements in the Mozilla Developer Network documents on using custom elements.

Now we can put <theme-select></theme-select> somewhere in our site, and we’ll end up with the following in our rendered markup:

<theme-select>
  <template>
    <button>Light</button>
    <button>System</button>
    <button>Dark</button>
  </template>
</theme-select>

On top of that, WebC will bundle up the styles and JavaScript needed for this component, which we can place in the <head> tag, or at the end of the <body> tag, or wherever we need them. Since the buttons are inside a <template> tag, they will remain invisible on the page until the custom element is registered by our JavaScript and the web component becomes defined, at which point the connectedCallback runs, and extracts the buttons from inside the <template> so that they become visible and usable.

Of course, you could also set up a Shadow DOM inside of your web component, if you wanted to, but you don’t have to.

There are plans to allow you to aggregate arbitrary HTML from your WebC components the way that styles and scripts are aggregated. This would mean that you could include a <template> as part of your component and guarantee that in the final markup there was only one copy of the template regardless of how many instances of the component you placed on the page.

Learn more about WebC

There’s a lot more to WebC than what we’ve covered so far. If you want to learn more, the Eleventy docs have a section on WebC which covers how to set up WebC with Eleventy as well as a lot of what you’ll need to know to use WebC in general, and with Eleventy specifically. Additionally, the WebC README in the GitHub repo contains documentation for WebC. And, finally, I’ve created a small website built with Eleventy and WebC at 11ty.webc.fun which contains little recipes for working with WebC, such as how to use WebC layouts in Eleventy. You can check out the recipes (there’s an RSS feed, too), or dig into the code on GitHub to see how I used WebC.

And if you have questions, the Eleventy Discord is a great place to bring them. We have a WebC tag in the support forum.

Ignore Eleventy Files With Environment Variables

2022-03-25T00:00:00Z

In this example, we exclude the "__docs" directory from a production build. Environment variables are injected as part of either the "start" or "build" command, with the cross-env package used to ensure compatibility with Mac or PC.

Watch how this works, or continue reading and review the code snippets.

Check out the design system project on GitHub.

Step one: Include environment variables

When developing an Eleventy project, it's common to include a couple of commands in package.json to run Eleventy as a local server and then to do a production-ready build for a web host.

Here's an example of a very basic set of scripts:

// located in package.json
"scripts": {
  "start": "npx @11ty/eleventy --serve",
  "build": "npx @11ty/eleventy"
},

I recommend running npm install cross-env so that including environment variables at this state works for both PC and Mac users.

We'll update both of our scripts to inject an environment variable called ELEVENTY_ENV with the value of "dev" for the start command, and the value of "prod" for the build command.

"scripts": {
  "start": "cross-env ELEVENTY_ENV=dev npx @11ty/eleventy --serve",
  "build": "cross-env ELEVENTY_ENV=prod npx @11ty/eleventy"
},

Step Two: Ignore files from within the Eleventy config

Within .eleventy.js - the Eleventy config file - we'll add just a few lines.

An if statement will check for whether our "prod" environment variable is available, and if so, we'll use Eleventy's ignore feature to exclude our __docs directory. This effectively prevents those files from building.

if (process.env.ELEVENTY_ENV === "prod") {
  eleventyConfig.ignores.add("./src/__docs/");
}

Note that in this example project, src is what the input directory has been customized to, and __docs is just an example of a directory you may want to exclude.

If you experience a build error, you may need to run npm install dotenv and then require it at the top of the config file, like so:

require("dotenv").config();

Here's more tips for managing environment variables in Eleventy.

Creating and Using Eleventy Collections

2021-11-11T00:00:00Z

What Are Collections?

Collections are groups of template* content.

One template can belong to multiple collections. These collections allow you to sort, filter, and perform other manipulations to customize the display of your template data.

Learning all the ways to create collections provides you architectural freedom in creating your Eleventy site!

* In 11ty terms, a template is any content file to be processed or rendered by 11ty. If you create a new Markdown file, you have created a new Markdown template, etc.

Creating Collections

Collections are most often created from tags, but can also be groups based on other features like file type or front matter data. They can even be created from local data.

Collections From `tags`

The simplest way to create a collection is with tags, and there are four syntaxes available.

Single tag:

tags: cat

Multi-word tag:

tags: cat and dog

Multiple tags, single line:

tags: ['cat', 'dog']

Multiple tags, multiple lines:

tags:
- cat
- dog

Assigning tags to many templates

While the examples shown are intended to be placed in a single template's front matter, there is an alternate way.

You may create a directory data file to assign tags to an entire directory of templates.

Given a directory called posts, create the file posts.json (the name must match the directory name) and add the following to assign your tags.

// posts/posts.json

{
  "tags": "posts"
}

Display Collection Data

Once you have several templates assigned to a collection - for example, blog posts - you may want to display some of the collection data.

This example works for both Nunjucks or Liquid templates and will output the name of each item in the posts collection:

<ul>
{% for post in collections.posts %}
  <li>{{ post.data.title }}</li>
{% endfor %}
</ul>

Other data available to display from a collection includes the following, as described on the 11ty Docs page for Collections:

inputPath: the full path to the source input file (including the path to the input directory)
fileSlug: mapped from the input file name
outputPath: the full path to the output file to be written for this content
url: url used to link to this piece of content.
date: the resolved JS Date Object
data: all data for this piece of content
templateContent: the rendered content of this template (excludes layout wrappers)

More Ways to Create Collections With `addCollection`

Let's look at the options available for creating collections beyond tags. These will be created within our .eleventy.js config, and use the addCollection function. This function allows us to create either new or modified collections.

Group Tags Together

To create a collection based on multiple tags, use the additional function of getFilteredByTags.

eleventyConfig.addCollection("tagGroup", function (collectionApi) {
  return collectionApi.getFilteredByTags("post", "page");
});

You may also perform additional operations once you have this new collections array to further filter or sort the items.

Glob By File Type

You can create a new collection by selecting all templates by file type using getFilteredByGlob().

There are a few stipulations for these collections:

the templates must be located in your "input" directory
- exceptions are: _includes, and templates marked as eleventyExcludeFromCollections
must be a template type supported by Eleventy (ex. .css wouldn't work)

eleventyConfig.addCollection("onlyMarkdown", function (collectionApi) {
  return collectionApi.getFilteredByGlob("**/*.md");
});

Collections From Template Front Matter Data

To create a collection based on front matter data, you can use a filter against all template content with getAll(). Then, you can access any front matter using item.data.customKey and return the filtered collection by just checking if that key exists. Or, you could extend this to check for a particular value.

This technique is useful for grouping similar content beyond tags.

eleventyConfig.addCollection("specialCollection", function (collection) {
  return collection.getAll().filter((item) => item.data.customKey);
});

Collections From Local Data

For accessing local data - as in, data returned from files within your _data directory - use the format getAll()[0].data.[customKey].

// Create collection from _data/customData.js

eleventyConfig.addCollection("customDataCollection", (collection) => {
  const allItems = collection.getAll()[0].data.customData;

  // Filter or use another method to select the items you want
  // for the collection
  return allItems.filter((item) => {
    // ...
  });
});

This is useful if you're not using pagination to generate template content. If you are using pagination, you can instead opt to assign paginated content to a collection via tags within the pagination process.

The `all` Collection

The special all collection is available by default for all template content, with no extra definition required. It is intended to allow you to access all of your site content, which is useful for things like sitemaps or RSS feeds.

To access all your template data, iterate over collections.all.

Filtered vs. Unique Collections

Instead of creating unique collections, existing collections can be passed into filters. Here are some considerations to help you choose which method to use.

Use filters:

to apply variance per template (ex. randomization)
to apply a repeatable modification like sorting (vs. the overhead of unique collections)

Use collections:

for consistent results per build throughout your site

Exclude Content From Collections

Sometimes you will want to remove a template from being included in collections. This attribute removes the template content from the all collection and any other defined collection.

---
eleventyExcludeFromCollections: true
---

Summary of Collection Creation Methods

tags: easily group content in multiple, flexible ways by template or directory
globbed file types: succinctly group related template content regardless of file system organization
front matter data: extend collection schema beyond tags by grouping content from your own custom meta
local data: benefit from the collection construct without resorting to pagination
filtering collections: mutate existing collections with repeatable operations, as well as allow randomization per template if desired

Filter Titles for RSS and Social Shares

2021-08-08T00:00:00Z

Sometimes, we want to use characters in our page titles that we can safely escape on our own sites, but which would be stripped out by social networks' link embeds or when pulled up in an RSS reader. For instance, an article called "<tfoot>: The Table Foot element" is usually stripped down to ": The Table Foot Element" to prevent cross-site scripting. If you use the < and > HTML entities instead, these same platforms will display your title as "<tfoot>: The Table Foot element," which is also not ideal.

You could choose to rework your titles so you don't run into this issue. Alternatively, you could automatically replace the offending characters with close lookalikes that won't be stripped out. Here, we'll replace the less-than and greater-than signs with the similar-looking ‹ and › single guillemets.

Accessibility tip: Replacing characters with other characters can pose accessibility concerns, as screen readers will attempt to pronounce the characters according to their intended purpose. As such, it's best to use this technique when you have no other option. Here, we're fine with replacing less-than and greater-than signs with guillemets because guillements are a kind of quotation mark, and most screen readers will treat them as just a brief pause, which is a better experience than not including the characters at all.

Step 1: Creating the Filter

We'll create an Eleventy filter that will take a string (our post title) and replace characters with their lookalikes.

In your Eleventy config:

eleventyConfig.addFilter('replaceStrippedCharacters', function(title) {
	return title
		.replace(/</g, '‹')
		.replace(/>/g, '›');
})

You can include any substitutions you need in this filter.

Go to your layout where you have your meta tags. You likely have a meta tag that looks like this:

<meta property="og:title" content="{{ title }}" />

Update this tag so that it passes your post's title through your new replaceStrippedCharacters filter:

<meta property="og:title" content="{{ title | replaceStrippedCharacters }}" />

Now whenever your link is shared on social media, the link embeds will display your character substitutions. You can validate this works using tools like Twitter's card validator.

Step 3: Filter Titles in RSS Feeds

Note: This section assumes you're using the official eleventy-plugin-rss plugin with the recommended sample Atom feed template to generate your RSS feeds.

Find the RSS template file you created while setting up Eleventy's RSS plugin. This template file likely loops over a collection of posts, doing something like:

{%- for post in collections.posts %}
  {% set absolutePostUrl %}{{ post.url | url | absoluteUrl(metadata.url) }}{% endset %}
  <entry>
    <title>{{ post.data.title }}</title>
    <link href="{{ absolutePostUrl }}"/>
    <updated>{{ post.date | dateToRfc3339 }}</updated>
    <id>{{ absolutePostUrl }}</id>
    <content type="html">{{ post.templateContent | htmlToAbsoluteUrls(absolutePostUrl) }}</content>
  </entry>
{%- endfor %}

Pass the <entry>'s <title> through the replaceStrippedCharacters filter:

{%- for post in collections.posts %}
  {% set absolutePostUrl %}{{ post.url | url | absoluteUrl(metadata.url) }}{% endset %}
  <entry>
    <title>{{ post.data.title | replaceStrippedCharacters }}</title>
    <link href="{{ absolutePostUrl }}"/>
    <updated>{{ post.date | dateToRfc3339 }}</updated>
    <id>{{ absolutePostUrl }}</id>
    <content type="html">{{ post.templateContent | htmlToAbsoluteUrls(absolutePostUrl) }}</content>
  </entry>
{%- endfor %}

Plugin: Object-Fit Focal Point

2021-08-07T00:00:00Z

This plugin adds an Eleventy Nunjucks shortcode to provide the functionality of generating an image's object-position value in order to keep the focal point in view when setting CSS aspect-ratio and object-fit: cover.

Test drive the results by using the utility app.

Docs for Object-Fit Focal Point

11ty RSS Reader Starter

2021-06-24T00:00:00Z

Provide permalinks to your favorite RSS feeds to populate a personalized RSS reader Jamstack application using Eleventy.

Bonus: This application was built on Twitch livestream, and recordings will be available on the 11ty Rocks YouTube channel. The course covers advanced 11ty templating.

Get the RSS Starter

Twitch Scenes 11ty Starter Template

2021-05-02T00:00:00Z

Scenes are optimal at 1280x720, and are included for:

Preshow, postshow, and break messages
Main scene with large capture area and host webcam capture
bonus slideshow layout

All scenes include a lower third for stream details, which also features embedded chat.

Get the Scenes Template

Layout Templating

2021-04-16T00:00:00Z

Body Classes for Pages and Layouts

A trick I originally learned from WordPress templates is to add a class on the body to identify the page being viewed. This helps you have page-specific style rules.

The {{ page.fileSlug }} is an Eleventy provided data variable that will be the original file name without the extension.

This will be the file name only, not the path. So /blog/post-one.md would render post-one.

Our logic includes the class of "home" when there is no fileSlug available since the the main index will not compute a fileSlug.

<body
  class="page--{% if page.fileSlug %}{{ page.fileSlug }}{% else %}home{% endif %}">

You may also add the layout in a similar way:

<body class="layout--{{ layout }}">

Note: If layouts are chained, then {{ layout }} will render out the lowest layout in the chain. So if blog.njk chains to base.njk, it will select blog.

Use Eleventy Templating To Include Static Code Demos

2021-04-02T00:00:00Z

This post assumes a foundational familiarity with Eleventy. If you're new to 11ty - welcome! You may want to start here.

This tutorial will showcase many features of Nunjucks templating. So, even if the tutorial's goal doesn't match your use case, you'll get more familair with using it as a templating language!

Project Brief

The goal of this Eleventy project is to create a single-page site that displays live code demos, like the setup on SmolCSS.dev. And we'll see how to extend it to a scoped context like is used for this ModernCSS.dev tutorial.

Here are the base requirements:

ease of managing demo content
demo code lives with demo content
each demo is an independent file
allow custom ordering of demos vs. date-based
RSS feed for demos
"Open in CodePen" functionality

Base Project Configuration

We're starting from an empty project with Eleventy installed and ready to run.

This tutorial will assume a customized input directory of src, and that you've created an index file where we'll eventually add the demo content.

If you're unsure how to do those things, follow my tutorial on creating your first 11ty site up until the Create the Blog step, and then come back to continue! 😊

You may also want to do the "Create a CSS File" and "Link to Stylesheet" sections in that tutorial if you are unfamiliar with how to do that with Eleventy.

Setup your index as index.njk as we'll primary be using Nunjucks for this tutorial.

Base Eleventy Setup for Single-Page Content

My favorite thing about Eleventy is the flexible content modeling. And most projects I do definitely benefit from the filesystem page creation, but for this project we'll need to disable that functionality.

So, our first step is to create a location for our code demos to live. Add src/demos, and then create the file demos.json with the following contents:

{
  "tags": "demos",
  "permalink": false
}

This is a directory data file and we define tags to create the demos collection. Then we set permalink to false to prevent page generation. These values will apply to all content within the directory, although you could still set front matter to override them for specific content.

Create a Demo File

Let's create our first demo. Add demo/centering.njk with the following content:

---
title: "CSS Centering"
order: 1
date: 2021-03-31
templateEngineOverride: njk, md
---

We include an order property that we'll use to order our demos within our single page rather than relying on Eleventy's default of date-based ordering. This is because we may create multiples on the same day, and on publish they may change order from what we see locally.

There is also a date included for purposes of correctly updating the RSS feed we'll be adding.

Finally, we add templateEngineOverride: njk, md because we will be mixing Markdown with Nunjucks content in this file and we want both to be processed correctly.

Demo Partial and Code Content

You may be wondering why we didn't add any content in the previous step. Instead of directly outputting the content within the demo Nunjucks file, we're going to populate Nunjucks variables to pass into a partial. This will enable consistency among our code demos and allow enhanced functionality.

Create src/_includes/demo.njk which will be our partial.

Let's determine the parts we need to output for each demo:

a title
a description
HTML
CSS

Now, since this is a case study of SmolCSS.dev, we're going to focus on showing the CSS as highlighted code. You can extend the following ideas to also show the HTML, or perhaps only the HTML, or even add JavaScript into the mix.

Within demo.njk let's populate our demo template:

{{ description | safe }}

<style>
{{ css | safe }}
</style>

<details>
  <summary>CSS for "{{ title }}"</summary>

  {% highlight "css" %}
  {{- css | safe }}
  {% endhighlight %}
</details>

<div class="demo">
{{ html | safe }}
</div>

Now this partial accepts the following variables:

title - used within the summary element since we're going to use the native HTML details element to enable collapsing the demo code
description - included with the safe filter because the content will be pre-compiled from Markdown into HTML
css - added twice so that it can be output as actual CSS within style tags, and also within a highlight block that will become the demo's sample code
html - added within a div.demo so that we can style the demo container around the passed HTML content

Let's go back to our first demo file and add the content within these variables:

{% set description %}

**Put down the CSS centering jokes**! This modern update is often the solution you're looking for to solve your centering woes.

{% endset %}

{% set css %}
.centering {
  display: grid;
  place-content: center;
}
{% endset %}

{% set html %}
<div class="centering">
  <span>Feeling Centered</span>
</div>
{% endset %}

{% include "demo.njk" %}

This sets the variables, and also includes the demo partial. For each demo file you create, continue this pattern of setting variables and including the partial.

Before we see some example output, this also assumes you are using eleventy-plugin-syntaxhighlight and have pre-included a prism theme.

Here's some starting CSS for the details, summary, and .demo:

details {
  margin: 2rem 0 0;
}

details pre[class*="language-"] {
  margin: 0;
}

summary {
  padding: 0.15em 0.5em;
  background-color: #0d3233;
  color: #fff;
  cursor: pointer;
}

summary:focus {
  outline: 2px solid #0d3233;
  outline-offset: 2px;
}

.demo {
  min-height: 30vh;
  padding: 1rem;
  border: 2px dashed currentColor;
}

Example Code Demo Output

Put down the CSS centering jokes! This modern update is often the solution you're looking for to solve your centering woes.

CSS for "Demo Output"

.centering {
  display: grid;
  place-content: center;
  min-height: 30vh;
}

.centering span {
  padding: .5em;
  outline: 2px solid;
}

Feeling Centered

Extend the Code Partial

The great thing about handling this via a partial that is passed variables to modify behavior is that you can build up more variables to alter the output when needed.

For example, maybe you don't always have HTML and description output and just want to show the CSS. So, you could create and handle for a hideDemo variable:

{% if not hideDescription %}
{{ description | safe }}
{% endif %}

{% if not hideDemo %}
<div class="demo">
{{ html | safe }}
</div>
{% endif %}

Which would be set as follows within your code file:

{% set hideDescription = true %}
{% set hideDemo = true %}

Resulting in only the details/summary appearing:

CSS for "Demo Output"

.centering {
  display: grid;
  place-content: center;
  min-height: 30vh;
}

.centering span {
  padding: .5em;
  outline: 2px solid;
}

Challenge: Extend this to make the open property for details a variable so that you have the option to set the details to visible instead of collapsed

Ordering and Output of the `demos` Collection

Now that we have our demo code files and partial figured out, it's time to figure out how to display this content. Remember - we turned off the default file system individual page creation.

We also had created a collection called demos when we defined the directory data file by assigning all of the files the tag of demos.

However, that collection will currently be date based as is the 11ty default. Since we want it based off the order front matter, we need to create a custom collection.

Add the following within .eleventy.js above the previous customization that updated the input/output directories:

eleventyConfig.addCollection("orderedDemos", function (collection) {
  return collection.getFilteredByTag("demos").sort((a, b) => {
    return a.data.order - b.data.order;
  });
});

This takes the demos collection and reorders it by our custom order key and returns a new collection called orderedDemos.

Now we can loop through the new collection to output it within our main index:

{% for demo in collections.orderedDemos %}
<article>
  <h2 id="{{ demo.fileSlug }}">{{ demo.data.title }}</h2>
  {{ demo.templateContent | safe }}
</article>
{% endfor %}

This is a minimal example where we are adding fully compiled demo templateContent within an article. We also pass in the main demo front matter title within an h2 that includes an id set to the demo's file slug in case you'd like to enable anchor links to each demo.

RSS Feed

To setup an RSS feed, install the eleventy-plugin-rss plugin and follow the instructions and use the example code from the RSS plugin docs.

The only alteration is to change from the posts collection to use our orderedDemos collection to correctly order the feed. In addition, you'll need to pass the reverse filter, resulting in the following start of the feed loop:

{%- for item in collections.orderedDemos | reverse %}

"Open in CodePen"

A bit of functionality that provides a valuable extra resource for our readers is the ability to export the demo code to CodePen.

I've abstracted my solution as used on SmolCSS.dev and ModernCSS.dev into the plugin @11tyrocks/eleventy-plugin-open-in-codepen.

Here's an example of configuring the plugin:

const openInCodepen = require("@11tyrocks/eleventy-plugin-open-in-codepen");

module.exports = (eleventyConfig) => {
  eleventyConfig.addPlugin(openInCodepen, {
    siteUrl: "YourSite.dev",
    siteTitle: "Your Site",
    siteTag: "yoursite",
    buttonClass: "your-button-class",
    buttonIconClass: "your-button-icon-class",
  });
};

Which would then make the shortcode postToCodepen available within your partial. You can include the button with the following updates:

// Set in your code demo file
{% set slug = page.url %}

// Add where you'd like it to appear in the partial
{% postToCodepen title, slug, css, html %}

Here is a working example of the button created by the shortcode (and including customizations specific to 11ty Rocks!) that will export the demo that we set up in this tutorial:

Prevent Global Affects on Demo CSS

If your use case is to populate demos within a context where you don't want your site's global CSS to cascade and affect your demo CSS, we can add a shortcode to help scope the styles.

But first, here's a starting set of styles for our .demo contents to reset most cascaded properties. You may find you need to add more properties here depending on what elements you are using in the demo. The goal is to prevent most global styles leaking through (and demo styles leaking out!) so that the demo styles are closer to being fresh from a native browser style base. If you are using a style reset, those rules may still come through for certain elements which is likely desireable.

.demo * {
  margin: 0;
  padding: unset;
  border: unset;
  border-radius: unset;
  color: unset;
  font: unset;
  font-family: system-ui, sans-serif;
}

Next, we'll create the shortcode. A shortcode can output content, and we'll actually use it to output both the <style> and .demo blocks, replacing what we previously had for the HTML in the partial.

Here is the content of the codeDemo shortcode, which intakes the css and html (if available). Then it finds the CSS class names, and replaces them with a version that has a "hash" (just a simple random number string for this context). Following that, it traverses the HTML and updates the matched CSS class names so that the hashed CSS selector matches the demo HTML.

eleventyConfig.addShortcode("codeDemo", function (css, html) {
  if (!html.length) return "";

  if (!css) {
    return `
<div class="demo">
${html}
</div>`;
  }

  const hash = Math.floor(Math.random(100) * Math.floor(999));

  const cssRE = new RegExp(/(?<=\.)([\w|-]+)(?=\s|,)/, "gm");
  const cssCode = css.replace(cssRE, `$1-${hash}`);

  let htmlCode = html;
  css.match(cssRE).forEach((match) => {
    // prettier-ignore
    const htmlPattern = match.replace("-", "\\-");
    const htmlRE = new RegExp(`(${htmlPattern})(?=\\s|")`, "gm");
    htmlCode = htmlCode.replace(htmlRE, `${match}-${hash}`);
  });

  return `
<style>${cssCode}</style>
<div class="demo">
${htmlCode}
</div>`;
});

A couple notes:

the indentation isn't an accident but necessary since we have setup our demo to process both Markdown and Nunjucks, and if those blocks are indented it fouls up that processing
this scoping method requires you to use class selectors, which means if you are using element selectors you will have to prefix them with a class which must exist in the passed HTML

Then in the partial, remove our previous block that output the HTML .demo and replace it with the following:

{% set htmlCode %}{{ '' if hideDemo else html | safe }}{% endset %}

{% codeDemo css, htmlCode %}

This still takes into account the option to hide the demo.

Important note about Nunjucks variables: They will pass through multiple instances of a partial if you include the partial multiple times within one file. If you are writing a tutorial and set the html variable at the top of the file, you can repeatedly update the css variable only prior to including the partial again and it will use the original HTML up until you update the html variable. This is super useful for tutorials showing how to progressively build something. In fact, this technique was created for exactly that purpose over on this tutorial for ModernCSS.dev.

Phew! That was a lot to learn about Nunjucks templating 😊 I'd love to know if this was helpful to you and see what you make with it! Reach out to @5t3ph on Twitter

A Deep Dive Into Eleventy Static Site Generator

2021-03-24T00:00:00Z

Eleventy (aka 11ty) is rising in the ranks among static site generators. This Node-based builder is attractive due to its zero-config starting point, purely static output, and ease of achieving the coveted top Lighthouse performance score of four perfect 100s.

In my article on Smashing Magazine, I've written about things that I would have found helpful to understand when I was getting started with Eleventy. It covers:

A brief intro to static site generators (SSG)
What makes it unique from other SSG
Getting started
Layouts
Templates
Filters
Shortcodes
Collections
Custom data
Pagination
Eleventy plugins
Starters
Is Eleventy a right fit for you and your project

Read the rest of A Deep Dive Into Eleventy Static Site Generator on Smashing Magazine

Essential Navigation Snippet

2021-03-09T00:00:00Z

The following snippet uses Nunjucks and could be added directly in a layout, or created as a layout partial - ex: nav.njk.

First, we set the variable of currentUrl to contain the current page URL, and if it matches the the nav item's URL, we add the appropriate aria to identify it as the current page.

In this example we are looping through the pages collection, which you may need to adjust to match your desired navigation content.


{% set currentUrl = page.url %}

<nav>
  <ul role="list">
    <li>
      <a {% if currentUrl === '/' %}aria-current="page"{% endif %} href="/">Home</a>
    </li>

    {% for link in collections.pages %}
    <li>
      <a
        {% if currentUrl === link.url %}aria-current="page"{% endif %}
        href="{{ link.url }}">
          {{ link.data.title }}
      </a>
    </li>
    {%- endfor %}
  </ul>
</nav>

This navigation strategy is in use for my Smol 11ty Starter

Bonus tip: Attach styles to the current item by using the CSS selector [aria-current="page"] to for example bold the current item, or change its color.

For deeper hierarchies and more complex navigation, you may want to use the official plugin:

Smol 11ty Starter

2021-03-09T00:00:00Z

An extremely minimal Eleventy starter to kickstart a simple multi-page site that provides a nearly opinionless foundation to continue building on.

You can preview this starter or jump right to the repo.

Use Smol Starter

Custom BrowserSync Options

2021-02-25T00:00:00Z

Including Opening a Browser on Launch

By default, Eleventy has the BrowserSync option to open a browser set to false.

Fortunately, it also provides a way to override the BrowserSync settings, so we can allow opening a browser with the following:

eleventyConfig.setBrowserSyncConfig({
  open: true,
});

If you use VSCode, you may also be interested in creating a launch task to enable running your Eleventy start command when you open your project.

Review the official 11ty docs on BrowserSync for more info.

11ty.Rocks on Youtube

2021-02-20T00:00:00Z

11ty Rocks is now on YouTube! Subscribe today so you don't miss a video. Content will be in support of topics explored here on 11ty.Rocks.

Subscribe to 11ty Rocks

VSCode Settings

2021-02-15T00:00:00Z

The following are intended to be added within your VSCode settings.json.

Extend Emmet for Nunjucks

There are two steps to getting Emmet to work for Nunjucks.

First, if you haven't already, install the Nunjucks syntax highlighting extension.

Next, add the following to specifically extend Emmet to Nunjucks:

"emmet.includeLanguages": {
  "nunjucks": "html"
},

You can also use this setting to extend to Liquid or other file types.

Language Specific Editor Settings

For myself, I have the following overrides for Markdown and Nunjucks which override my standard setting of 80 characters per column:

"[markdown]": {
  "editor.wordWrapColumn": 100,
  "editor.wordWrap": "bounded",
  // Turned off to prevent Emmet when writing code fenced blocks
  "editor.quickSuggestions": false
},
"[nunjucks]": {
  "editor.wordWrapColumn": 100,
  "editor.wordWrap": "bounded"
},

You can extend these to other templating languages you may be using.

Site Metadata

2021-02-15T00:00:00Z

The _data directory is an expected location for various data sources for your Eleventy site.

A convention you'll see variations of in several starters is a data file to hold site metadata. This concept is useful for creating extendable solutions so that certain template bits don't need repeated or started from scratch everytime.

Here's the one that's included in my 11ty Netlify Jumpstart which you can adapt to your own needs:

// Located in _data/meta.js
module.exports = {
  // NOTE: `process.env.URL` is provided by Netlify, and may need
  // adjusted pending your host
  url: process.env.URL || "http://localhost:8080",
  siteName: "",
  siteDescription: "",
  authorName: "",
  twitterUsername: "", // no `@`
};

Then, you can access that data in templates and content by using the filename first, followed by the data key of what you'd like using dot notation.

For example, if I wanted the siteName I could access it within Nunjucks as:

{{ meta.siteName }}

See this idea in use for the 11ty Netlify Jumpstart base template

Modifying Permalinks

2021-02-15T00:00:00Z

Often permalinks are changed via front matter, but you may wish to apply permalink changes in a directory data file so that the change will apply to all content within a directory at once.

Remove Directory Prefix

As noted in the directory data file tips, you may wish for content contained in a directory to actually appear to live off of root:

permalink: "/{{ page.fileSlug }}/"

page is provided by 11ty and you can learn more about the page variable in the official docs

Add Date

The following will keep the existing structure based on directory location (provided by page.filePathStem), but prepend it with the content's date:

permalink: "/{{ page.date }}/{{ page.filePathStem }}/"

Take a minute to learn about date handling in 11ty

Create Permalink From Title

You may want to use your post title for creating the permalink instead of the default of the file path/filename.

Conveniently, front matter data is available to permalink so you can actually use any front matter to modify the permalinks structure.

However - you need to use it alongside the slug filter to ensure it's URL-formatted.

permalink: "/{{ title | slug }}/"

If you tend to use code formatting or perhaps emojis in your titles (like I do) you may want to modify the slug filter.

Excluding and Moving Content

Permalinks can also be used to prevent content output, or change it's location.

Excluding Content Output

2021-02-15T00:00:00Z

Prevent Page Generation Output

Sometimes you may want to create content using your preferred templating language but not actually output an individual page.

The preferred way to do this is via permalink:

permalink: false

If you want this to apply to an entire collection, you can do this in a directory data file. This example is used for this very site to create the resource content on the home page:

{
  "tags": "resources",
  "permalink": false
}

Read more about setting permalink to false in the official docs

Excluding Content From Collections

Within a directory intended to be content for a collection, you may have content, such as the index, that you do not want included in the collection itself.

To entirely exclude the content from any collection, set eleventyExcludeFromCollections to true:

eleventyExcludeFromCollections: true

Directory Data File

2021-02-15T00:00:00Z

Create a Directory Data File

To create a directory data file, add a json file within your directory with the same name as the directory.

For example, within /posts/ create posts.json.

Assign Tags and Layout

Most often, I use directory data files to quickly create collections via tags and also to assign all the directory content to a layout.

{
  "tags": "posts",
  "layout": "post"
}

If needed, you can still override these values within the front matter of individual files.

Change Permalink Structure

Another very handy feature is the ability to change the permalink structure for all content within directory.

Here's one example of assigning content to live off the root instead of retaining the directory as a prefix:

{
  "permalink": "/{{ {{ page.fileSlug }} }}"
}

Review more permalink structure tips

Changing Content Output

2021-02-15T00:00:00Z

The following techniques are applied via front matter.

The base file that you are using to create the altered content can use any of Eleventy's templating languages, and use all the features that language provides. For example, you could use Nunjucks or Liquid and loop through a collection to create JSON output.

Change Content's Output File Type

One of Eleventy's super powers that allows you to exceed the traditional limits of static is in using templating to create any file type output.

This is often used to create sitemaps and RSS feeds.

Changing the file type is done by simply appending the desired extension via the permalink:

permalink: "/{{ page.fileSlug }}.txt"

Learn more tips for constructing permalinks

Output Content Outside the Eleventy Filesystem

This is again done via permalink, and requires also setting permalinkBypassOutputDir: true which allows making our permalink relative to the project root using ./.

permalink: ./functions/{{ page.fileSlug }}.txt
permalinkBypassOutputDir: true
eleventyExcludeFromCollections: true

Notice we're also excluding it from all collections since we are intentionally creating it for purposes outside of our main site structure.

This technique is used to create page data for use by my social image plugin

Single-Page Setup (recorded livestream)

2021-02-15T00:00:00Z

I joined Colby Fayock on Twitch in a slightly chaotic hour where I began building SmolCSS.dev with Eleventy.

Check out the recording and learn more about setting up Eleventy content for use in a single-page site, including advanced template and layout features using Nunjucks.

Watch Recording

11ty Quick Tips

2021-02-15T00:00:00Z

Useful snippets and ideas for managing and creating 11ty projects.

Includes tips on VSCode settings, site metadata, permalinks, and more!

View All Tips

Using Template Content as Data for 11ty

2021-02-15T00:00:00Z

This tutorial describes a technique I've used in several of my 20+ Eleventy projects to push Eleventy to exceed the traditional limits of static.

New to Eleventy? Start with my written tutorial or 20 minute video course.

Creating Content as Data

One way we can create data in Eleventy is via the _data directory, which is great for small arrays or for pulling in content from a CMS. Content contained in _data is then available for either pagination or directly for uses such as looping to output content.

But what if your content will all be local and intended to output on a single page, and you would like to use templating or other rich features that would be cumbersome inside JSON? This is the type of scenario where you want to create "content as data."

Step One: Create a Collection

Let's imagine our scenario is a site where we'll provide book reviews.

For ease of accessing our review content data, we'll create a collection.

In your input directory, create the reviews directory, and then inside of that create the file reviews.json which will be a directory data file.

{
  "tags": "reviews"
}

This is now creating the reviews collection by assigning it as a "tag" (the standard Eleventy way to create a collection) for all content that will live in this directory.

Step Two: Prevent Page Generation

With only the previous step in place, if Eleventy is running and you add a file - such as firstreview.md - in the reviews directory, you will have reviews/firstreview.html created as a page in your site's output directory.

Since our intention is to use this content as data, we need to prevent this page generation.

Preventing generation of files in the site's output directory is handled by setting permalink: false, so we'll update our directory data file:

{
  "tags": "reviews",
  "permalink": false
}

Step Three: Create Collection Content

Now you can create files using any supported templating language within the reviews directory and take advantage of all the templating features it offers.

For example, here's a possible setup for our book review content type using Markdown:

---
title: "Paddington Bear"
author: "Michael Bond"
rating: 4.5
buyLink: "/"
---

I enjoyed this book very much, and so did my 3 year old.

Step Four: Output Collection Content

Once you have some content available, and since we've created it within a collection, we can now easily access it for output within a loop.

You may choose to create this loop within your index file, such as index.njk, or perhaps you would rather it be part of the layout that your index uses, such as base.njk.

You can choose another templating language to loop over your content, but we're going to stick with Nunjucks for this example.

Our Nunjucks loop might then look as follows for accessing the book reviews:

{% for review in collections.reviews %}
  <article>
    <h2>
      <a href="{{ review.data.buyLink }}">{{ review.data.title }}</a>
    </h2>
    <ul>
      <li><strong>Author</strong>: {{ review.data.author }}</li>
      <li><strong>Rating</strong>: {{ review.data.rating }}/5</li>
    </ul>
    {{ review.templateContent | safe }}
  </article>
{% endfor %}

Let's examine a few key aspects of that loop for successfully accessing and outputting the data as content:

Front matter values are accessed off of the data nested object
The compiled non-front matter content is available within templateContent
To ensure any HTML in the compiled template is rendered and not escaped (which would cause it to appear as additional text on the page), we also use the safe built-in filter
Avoid wrapping the templateContent within a paragraph since it arrives compiled and already includes HTML elements as appropriate

And with that you've successfully created and output content as data!

Going Beyond Static Sites With Eleventy

2021-01-28T00:00:00Z

The following is the written version of my talk at TheJam.dev 2021

Key Eleventy Features

100% Static Output

First, I was very drawn to it being able to be purely static. At it's most essential level, it can be a drop-in replacement for tools like Gulp, and can be built with good ole HTML and CSS.

A huge selling point for me was that there is zero boilerplate client-side JavaScript.

Developer-Mode Conveniences

Eleventy includes BrowserSync when using the --serve flag which provides hot-reload as you make changes. There's also full console logging of what was changed or had errors, and the option to quiet this output.

Minimal Opinions, Highly Configurable

Technically, the only requirement besides Eleventy is an index file which can be created in any of the languages. Mine is usually Markdown that feeds into a Nunjucks layout which we'll talk about in a bit.

Once you get a feel for how things work, you can begin to add your own opinions by updating the config, which is expected to be a root file called .eleventy.js

Here you can do things like customize your input and output directory, and add other watch directories. It's also the entry point for plugins, and where you'll hook in additional templating, data, and content features.

10 Templating Languages

With 10 templating languages available, an early realization was that I could re-purpose some of my organization preferences from both my React and WordPress days to create templates and components. I've grown a preference for a stack of HTML, Nunjucks, and Markdown.

The extra languages are a nice to have, and can be added in as you find a need for them.

Templating Features

As I mentioned, my preferred stack with Eleventy is HTML, Nunjucks and Markdown. Here's the full list of currently available templating languages:

The first "a-ha" moment that made me really excited about Eleventy was the ability to mix templating languages.

This takes two primary forms:

Mix in the same file (ex. Nunjucks and Markdown)
Mix between layouts (Markdown file uses Nunjucks template)

Layouts are special templates that can be used to wrap other content. An example of this is having index.md contain your home page text content and Frontmatter for the page title, and have it point to the layout of base.njk which is an HTML5 boilerplate and uses template tags to display the title value and the Markdown content.

Eleventy also has a feature called layout chaining. So, you could create an article content type and a news content type that both chain to a page layout, and the page layout could chain to the base layout.

Within layouts and templates, you can use the syntax of the language you choose to include other files as partials. Or, you can create reusable content with shortcodes and manipulate content with filters. We don't quite have time to go through those features today, but the key point is that they allow even more customization and flexibility within your layouts and templates. You can review that info by visiting the 11ty docs on configuration.

One of the most powerful features related to templating is being able to define overrides for the template engine which you can do per file or in the Eleventy config*.*

On a per-file basis, we can place it in Frontmatter. Here we define that the template should be first consumed as Nunjucks, then Markdown. Eleventy will work for basic loops that mix languages, but adding filters or formatting can cause issues that the template engine override will resolve.

---
templateEngineOverride: njk, md
---

## Featured Person

{% for name in people | randomPerson %}

- {{ name }}

{% endfor %}

Data

The example that was just shown actually was setup to use what Eleventy calls "custom data".

An optional directory can be included called _data and in there you can put things like JSON or JavaScript module exports. The name of the file is then made available throughout Eleventy to access that data. So in the "Featured Person" example, there is a file located in _data/people.js that exports a simple array, and we can then access that in any template by the filename of "people".

module.exports = ["Mary", "Claire", "Steph", "Andy"];

But you're not restricted to flat or simple local data. You can also perform a fetch for external data and import any needed functionality to get and format the data you want Eleventy to use.

Here's a simple example fetching a path from a random cat picture API:

const axios = require("axios");

module.exports = async () => {
  const result = await axios.get("https://aws.random.cat/meow");

  return result.data.file;
  // Ex: https:\/\/purr.objects-us-east-1.dream.io\/i\/image1-4.jpg
};

The important note here is that the fetch is done at build time, not client-side. For fetching from a CMS this is highly desireable. For content you want to keep more fresh, you can use services like IFTTT to do a periodic request if your site host provides webhooks to trigger a build. Of course, that is a static site limitation that is not unique to Eleventy.

We'll talk a bit more about data handling when we get to our examples.

Content Management

A key feature for content in Eleventy is "collections". If you come from the WordPress world like I do, you can think of these similair to how adding tags creates sets of content. In fact, Eleventy uses the same convention of tags as one way to create a collection.

Tags can be added in Frontmatter, either as a single string or as an array.

But the slickest way is to create a directory data file. The directory data file needs to be named the same as the directory, and can be either JSON or JavaScript. It can hold any values that you would otherwise have to repeat in Frontmatter for all related content.

So in this example located in our posts directory, we create posts.json and define the tags as well as the layout:

{
  "layout": "post.njk",
  "tags": "posts"
}

Now, we can access the posts collection within any of our templates:

{% for post in collections.post -%}
- [{{ post.data.title }}]({{ post.url }})
{% endfor %}

Feature Integration

As we saw with the data example that used axios for fetching, another benefit of Eleventy is that it is built with Node. And you can use anything in the Node and JavaScript ecosystem at build time.

Let's look a classic issue that is solved by having access to JavaScript at build time: making sure your footer has the correct copyright year.

In Eleventy, we could export this as data, but we can also create what is called a shortcode to be able to output it. This snippet actually comes direct from my 11ty.Rocks config samples, and likely looks very familiar to those of you who frequently write JavaScript:

eleventyConfig.addShortcode("year", () => `${new Date().getFullYear()}`);

This snippet gets placed in the .eleventy.js config, and then you can use it in your templates.

There is also a fledging plugin ecosystem. Plugins come in as packages, and are included via the config as well. They range in complexity, but most provide access to shortcodes, filters, or other types of transforms that have the advantage of already being aware of how Eleventy works.

A bonus benefit in my journey with Eleventy was finally publishing a package since I wanted to release an Eleventy plugin, and now I have two:

The best way currently to discover all Eleventy plugins is to search by the tag eleventy-plugin on npm.

Flexible Output

I'm hoping you've heard a few things that have you interested in Eleventy, but this next feature is what opened the door to the examples I'll be sharing shortly.

By default, Eleventy works as you would expect from other similair static site generators. You create a file using whichever template language type and it ultimately outputs HTML.

But Eleventy, by way of defining permalinks, allows you to change the file type and place the resulting file anyway in the system.

A small example of this being useful is in creating the site's RSS feed, which is actually demonstrated by the official Eleventy blog starter and supported by an official plugin which provides some filters to assist in producing things like absolute URLs and correctly formatted dates.

An additional way to use this feature is to be able to create a JSON file of page data that is actually constructed within a Nunjucks template and accesses an existing collection. The benefit of this is that you have the compiled template content available if say the page content itself was created in Markdown.

And using permalinks, we can both change it to be the .json file type but also place it outside of the src directory, thus excluding it from the site output but making it available for other processes.

What I've just described is how I was able to create a dynamic and synced data file that is used to create social media images. In that process, I kick the JSON file to a functions directory in which there is a Node Puppeteer script that loops through that data and loads it into an HTML template to take a snapshot and save the image.

Community

Before we move on to examples, I wanted to note that despite Eleventy being just at three years old, there is an active, passionate community.

Search the phrase "built with eleventy" on Twitter and you'll get enthusiastic folx telling you all about it, often with a blog post about their experience.

Where some platforms have the concept of themes, Eleventy uses the term "starter" and there is a growing collection to choose from. With 10 templating languages available, there are many opinions of how things should be done, so you're sure to find one to help get you off the ground.

The market for content about Eleventy is still young, which I find exciting and have personally embraced. But when you really can't find the answer, you can tag the offical @eleven_ty account on Twitter and Eleventy's creator, Zach Leatherman, will often answer or RT for reach to the community. He's also quick to amplify blog posts and other things made by and for Eleventy if you tag the account.

Create an Eleventy Site in 3 Minutes

These steps are also very similar to what is described in my tutorial on building your first 11ty site which includes code samples for all steps.

This 3 minute video is followed by the transcript and a few code samples:

Ok! So I hope you're excited and maybe even have a project in mind to try to build with Eleventy!

So now we're going to build an Eleventy site in 3 minutes and following that we'll see the features we talked about in action and will follow this with some examples of going beyond static with Eleventy.

The first important lesson after we init a new project and get ready to install Eleventy is that it is a scoped package, so you install it with @11ty/eleventy.

Once the installs complete, we'll open package.json and update the default scripts section. This enables a start command to run 11ty with hot-reload, which is provided by Browsersync that comes bundled as part of 11ty's --serve directive.

"scripts": {
  "start": "npx @11ty/eleventy --serve",
  "build": "npx @11ty/eleventy"
},

Next, we create the config file to perform an optional step which is to update our input and output directory, my preference being src for "input" and public for the output.

module.exports = function (eleventyConfig) {
  return {
    dir: {
      input: "src",
      output: "public",
    },
  };
};

Then we need to create a layout file and an index file. You can certainly combine these steps, but to take full advantage of templating features, I recommend using layouts from the start.

Eleventy expects layouts to be located in the _includes directory, and we'll create a Nunjucks file called base. Our layout will use the HTML5 boilerplate, and we'll prepare it for the incoming content by adding the variable of {{ title }} which will be provided by frontmatter. We'll also stub out a nice semantic starting point for the body, adding the title again as the h1 and use the template variable for content followed by the safe filter to say we expect and want to allow any HTML content here.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Going Beyond Static Sites With Eleventy</title>
  </head>
  <body>
    <header>
      <h1>Going Beyond Static Sites With Eleventy</h1>
    </header>
    <main></main>
  </body>
</html>

Now in our src we'll create index.md and add the frontmatter key of title with a nice "Hello World", and a small message to make sure our content is working. We'll also attach it to our layout with the frontmatter key of layout and set the value to the filename of base.njk.

---
title: Hello World
layout: "base.njk"
---

Hello Jamstack fam!

Finally, we'll open Terminal and run the npm start command we setup which launches a local server. We do still have to open this in a browser ourselves, but you'll see that we have successfully created our first page.

We'd like a little style for this, so let's create style.css. The one trick here is we need to make Eleventy aware of this CSS file as it's not presently included, but first we'll link to it in our base layout. Then back in our config we'll add style.css as a passthrough copy target, and now we have a lovely sans-serif theme kicked off.

// Add within .eleventy.js
eleventyConfig.addPassthroughCopy("./src/style.css");

Finally, to add a blog, we'll create a posts directory and add my-first-post with a title and a bit of content, then a directory data file using the directory name as the filename, to send it to the base layout and add the tags to create theposts collection.

And back in our index we'll loop over the new posts collection.

{% for post in collections.post -%}
- [{{ post.data.title }}]({{ post.url }})
{% endfor %}

And there we have essential basics of getting started with Eleventy.

Going Beyond Static

With Eleventy, I can go from idea to publish in a matter of hours, with only the speed of typing in my way. 😉 It's made me feel the magic of web development again.

So I'd like to share some of those projects as examples of going beyond static, which to me means using the features we discussed to their full capability to extend beyond just HTML output from static, local content.

Style Stage - Non-CMS Community Contributions

My first large project with Eleventy was StyleStage.dev which is a modern CSS showcase styled by community contributions.

The key here is that anyone can contribute a stylesheet.

The way that is setup is by allowing contributors to add their own JSON file within the _data directory. Those then get globbed together to create the collection for use on the site, and also a JSON file is created to generate social share images like I described earlier.

Eleventy in this instance enables a simple mechanism for contributors that doesn't require managing a CMS or worrying about other forms of authorization because GitHub helps provide that layer. Coupled with Netlify, any new PR gets it's own deployed branch to enable me to reveiw submissions to ensure they meet the guidelines and help work with the contributor to resolve any issues or bugs.

This has enabled contributors of many skill levels, and there are 50+ styles available for review on the site today.

Generators

Next we'll go a bit more outside the box with a series of generators that are intended to:

produce an asset, or
provide an environment instead of a static site for publish

Email Generator

First up is the example of an email generator.

In this case, front matter is heavily leveraged to populate areas of the table-based template layout, but Markdown is used for the main content.

The generator is setup to allow initial email styling with Sass. With the build command, the compiled template content is fed through a filter that hooks in the juice package which provides the style inlining functionality that is required for the best email style compatibility.

So the output in this case is the compiled email template, but during the build Eleventy provides a comfortable environment where I can tuck away the fact that ultimately an email is comprised of tables for layout.

Get the email generator on GitHub!

Web Component Generator

This year I also started learning about web components. But I found them a bit uncomfortable to build as a hobbyist who was looking for a couple small use components versus building a whole system.

I thought I may not quite be able to accomplish compiling a web component with Eleventy, but two hours later I had a proof of concept deployed. The resulting environment allows generating web components in a way that separates concerns, and enables including them in pages to test the component during build out.

To accomplish this, the generator exploits the layout functionality to inject the web component's scripts and styles into the required location to create the final JavaScript file.

The web component's HTML template is created as Nunjucks file, and the associated script and style is created in the _includes as if they were layout partials. To dynamically tie it all together, the generator expects that the Nunjucks template and the directory for the scripts and styles in _includes share the same kebab-cased filename.

Any created web component is fed into a unified components Nunjucks template that allows bringing all the pieces together to be ready for what is ultimately output as a JavaScript file ready to be used as a web component.

In this case, the site could theoretically both create and consume the web components if the author so desired. Since this is still a POC, there's room to improve by adding a transpiler or enabling Sass in addition to vanilla CSS.

Learn more and demo the generator and clone it for your own use!

CSS Houdini Worklet Generator

Next up is probably my most unusual idea to date.

One area of CSS I hadn't had the opportunity to explore until recently was Houdini.

When I went to try to understand it better, I found many wonderful resources but no existing starting environment to build from.

In the case of CSS Houdini, it is actually a requirement to be running on a secure or local server. The file used for Houdini is called a worklet and is created with JavaScript. There are a few flavors of Houdini available but the currently best supported version is the Paint API. This API will look familiar to those of you who have used canvas. And a disclaimer here: everything that I just said and am about to show you was new to me, so there is ample room for improvement!

Presently, this generator is setup to only create one worklet, because ultimately the idea is that the produced files can be published as a package to be available for wider consumption. However, it could be extended to create a set of related worklets.

For this generator, the worklet is created all in itself, unlike the email or web component generators which compile files together.

But Eleventy helps provdie the local server, and the base template to serve the worklet as well as the currently required polyfill to enable testing. Plus since Eleventy runs on Node and therefore we've already got a package file available, it made it easy to prepare it as an all-in-one solution to publish the final package from.

For this generator, the benefit of Eleventy was providing a slim environment that provided the required local server and no extra fluff beyond that.

Learn more and get the CSS Houdini Generator on GitHub!

ButtonBuddy

Cool, so we've talked about features inherit to Eleventy that allow us to do things beyond generate a simple static site.

But what if you do need some client-side JavaScript?

For most of my projects, I either really don't need any JS, or a small enough bit that I could write it vanilla with no worries about compatibility. But then I had the idea for a client-side generator that I really needed to include functionality from available packages.

My web app, ButtonBuddy, helps you check or create an accessible color palette for your buttons, and the main package I needed to include was to do the calculations to determine the contrast ratio.

With this project, I learned there were many ways folx were adding bundling or transpiling, but personally I was familiair with Parcel from projects in my previous work life.

So here I need to give credit to Michelle Barker who created the eleventy-parcel starter which was a beautifully slim setup that hooked in Parcel minimally at the last step of the build process.

Within no time, I was able to add in the necessary bits to my in-progress project and was off to the races using ES6 for ease of putting together the web app functionality. Did I mention Eleventy has a great community? 🙂

I wanted to include this example if you have had concerns that Eleventy was going to lock you into only static without an easy plan to include modern, client-side JS when you really needed it. As I mentioned, I do have a history with React and Gatsby, and I'll say that Eleventy + Parcel got me precisely what I needed in a very efficient manner.

Check out this project at ButtonBuddy.dev

Summary

Eleventy has given me a bit of a can't stop, won't stop attitude toward building for my own joy of the craft of web development. And these mini projects have been amazing for learning new things, getting feedback, and growing my network and connections to a whole new community of awesome web makers.

So whether you're looking for a replacement for an older setup but otherwise content with truly static, or you're interested in upgrading your playground environment and exploiting some of the other features we talked about today, I encourage you to give Eleventy a try!

Be sure to bookmark this site, or pick up the RSS feed to keep updated of new resources! Reach out on Twitter if you have questions or suggestions of topics to cover.

11ty CSS Houdini Worklet Generator

2020-12-15T00:00:00Z

CSS Houdini worklets require a server to run. While there are many ways to create an environment for developing and testing your worklet, as a static site generator, Eleventy provides a slim way to get setup and testing quickly so you can focus on creating your worklet!

You can preview the included worklet example on this CodePen.

Details and Template

11ty Filters for Tags

2020-11-24T00:00:00Z

`hasTag` Filter

Useful when using a layout for multiple collection types, such as to provide a different call to action or link.

Usage within a layout for a single page:

{% if tags | hasTag('post') %}

eleventyConfig.addFilter("hasTag", (tags, tag) => {
  return (tags || []).includes(tag);
});

Could be genericized to hasItem and used on any array data type.

Filters for Data Arrays in 11ty

2020-11-24T00:00:00Z

These filters can be used on Eleventy collections or any custom data that presents as an array.

`randomItem` Filter

Return a randomly picked item from a given array.

Usage: {{ for item in collections.all | randomItem }}

eleventyConfig.addFilter("randomItem", (arr) => {
  arr.sort(() => {
    return 0.5 - Math.random();
  });
  return arr.slice(0, 1);
});

`limit` Filter

Return a subset of array items limited to the passed number.

Usage: {{ for item in collections.all | limit(3) }}

eleventyConfig.addFilter("limit", function (arr, limit) {
  return arr.slice(0, limit);
});

`randomLimit` Filter

Given a collection and a limit in addition to the current page.url, returns the requested number of items excluding the current one. This is useful for showing additional posts without the current one being repeated in the list.

Usage: {{ for item in collections.all | randomLimit(3, page.url) }}

eleventyConfig.addFilter("randomLimit", (arr, limit, currPage) => {
  // Filters out current page
  const pageArr = arr.filter((page) => page.url !== currPage);

  // Randomizes remaining items
  pageArr.sort(() => {
    return 0.5 - Math.random();
  });

  // Returns array items up to limit
  return pageArr.slice(0, limit);
});

`pluck` Filter

The pluck filter is useful if you want to return a subset of an array based on some known attribute values, such as given an array of titles.

Version 1: Check against a value array:

{%- set pickedPosts %}
["Title A", "Title B"]
{%- endset -%}
{% for post in collections.all | pluck(pickedPosts, 'title') %}

eleventyConfig.addFilter("pluck", function (arr, selections, attr) {
  // Assumes this is receiving a collection, hence the `data`
  // If custom array such as from _data, update accordingly
  return arr.filter((item) => selections.includes(item.data[attr]));
});

Version 2: Check against a single attribute

// Useful for getting a subset based on a secondary data list
{% for category in categories %}
// Then pluck just items in that "category"
{% for post in collections.all | pluck(category, 'category') %}

eleventyConfig.addFilter("pluck", function (arr, value, attr) {
  return arr.filter((item) => item.data[attr] === value);
});

Filters for 11ty Content

2020-11-24T00:00:00Z

`markdown` Filter

Sometimes you want to convert a specific bit of content into Markdown. For example, if you have created content as JSON formatted custom data within _data. In that case, you maybe don't want to use pagination to create pages but instead to loop through it somewhere.

By tapping into the included markdown-it Markdown parser that is used by Eleventy, we can create a filter to use adhoc on content:

// Add above your Eleventy config
const markdownIt = require("markdown-it");

// Add within your config module
const md = new markdownIt({
  html: true,
});

eleventyConfig.addFilter("markdown", (content) => {
  return md.render(content);
});

To use this filter, you'll also need to pass it through the Eleventy-included safe filter to render insted of escape the compiled HTML:

{{ data.content | markdown | safe }}

Note: Since the Markdown conversion will include elements like paragraphs, don't place the line including that content within a <p> or you will end up with extra paragraphs.

`excerpt` Filter

This filter expects the full post content - post-processing - which it will strip HTML tags from and then limit to approximately the first 200 characters. The function backtracks to the space prior to the 200th character to prevent splitting words.

Usage: <p>{{ post.templateContent | excerpt }}</p>

eleventyConfig.addFilter("excerpt", (post) => {
  const content = post.replace(/(<([^>]+)>)/gi, "");
  return content.substr(0, content.lastIndexOf(" ", 200)) + "...";
});

`addNbsp` Filter

This filter is already available to you are using the Social Images plugin

This filter intakes a string, such as for a page title, and inserts a non-breaking space - nbsp; - between the last two words to prevent a single word dangling on the last line (called an "orphan" by typographers).

Usage: {{ title | addNbsp }}

eleventyConfig.addFilter("addNbsp", (str) => {
  if (!str) {
    return;
  }
  let title = str.replace(/((.*)\s(.*))$/g, "$2&nbsp;$3");
  title = title.replace(/"(.*)"/g, '\\"$1\\"');
  return title;
});

`stripFilename` Filter

Useful if using a value such as layout - which returns the full filename - in an alternate scenario, such as for part of a class name as shown.

Usage: <body class="layout--{{ layout | stripFilename }}">

eleventyConfig.addFilter("stripFilename", (file) => {
  return file.replace(/\.[^/.]+$/, "");
});

Note: If actually using with layout, and your layouts are chained, it will return the "last" layout in the chain. Ex: if the filter code lives in base.njk but the page content is post.njk, will return post when using this filter.

Customizing 11ty Collections

2020-11-24T00:00:00Z

Collections from Custom Data

If you have custom data that you don't need paginated but do need to customize the returned items, here's how to create it as a collection.

In this example, replace customData with the filename of your custom data.

eleventyConfig.addCollection("customDataCollection", (collection) => {
  const allItems = collection.getAll()[0].data.customData;

  // Filter or use another method to select the items you want
  // for the collection
  return allItems.filter((item) => {
    // ...
  });
});

`randomizedPosts` Collection

Create a randomized version of a tag collection.

As opposed to the random filters, a collection will persist throughout your site, whereas filters used on multiple pages will produce randomized results per page.

eleventyConfig.addCollection("randomizedPosts", function (collection) {
  return (
    collection
      // Change to the name of your tag
      .getFilteredByTag("post")
      .sort(() => {
        return 0.5 - Math.random();
      })
      // Optional limit, remove if unwanted
      .slice(0, 3)
  );
});

Collections Based on Frontmatter

Useful for when you may not want to create the collections by duplicating tags and instead use a custom frontmatter key.

eleventyConfig.addCollection("specialCollection", function (collection) {
  return collection.getAll().filter((post) => post.data.customKey);
});

Managing `.env` Variables

2020-11-23T00:00:00Z

Environment variables are a way to retrieve values that may come from build processes, and are sometimes sensitive, like API keys. For local development access, those are typically stored in a .env file at the root of your site, and not checked in to version control in order to keep them private.

Creating and Accessing `.env` Variables

You you may want to create your own variables to determine the difference between your production vs development environment.

For this, you'll start with a modification to your build scripts, such as:

"start": "cross-env ELEVENTY_ENV=dev eleventy --serve",
"build": "cross-env ELEVENTY_ENV=prod eleventy",

I'm including cross-env for cross-platform compatibility.

Then add to a _data file of your choice, perhaps to your site's meta.js or a dedicated file:

module.exports = {
  env: process.env.ELEVENTY_ENV,
};

Access `.env` Value With Templating

Then you can output the value as demonstrated for the other meta keys, or use within templating such as to control whether or not analytics scripts are included:

{% if meta.env == 'prod' %}
// analytics here
{% endif %}

Access `.env` Values in `.eleventy.js`

If you are trying to access environment values in .eleventy.js, you will access them directly as process.env.ELEVENTY_ENV.

If you set .env variables in an actual .env file and/or as part of your build pipeline, you will need to include the following in the custom _data or .eleventy.js file:

// First `npm install dotenv`
require("dotenv").config();

// Example access
const API_KEY = process.env.API_KEY;

.eleventy.js Config Samples

2020-11-23T00:00:00Z

A collection of filters, shortcodes, and other tips for extending 11ty, such as working with dates and extending built-in filters.

View All Samples

11ty Slugs and Anchors

2020-11-23T00:00:00Z

`slug` Filter Extension

The default slug filter uses slugify under the hood, but sometimes the default behavior isn't quite enough if you are using special characters, including emoji.

We can override the filter to enable strict mode, enforce lowercasing, and optionally add any other characters you encounter being problematic. In this case, I'm enforcing removing " because I have experienced issues without explicitly defining it.

Usage: {{ title | slug }}

// Import prior to `module.exports` within `.eleventy.js`
const slugify = require("slugify");

eleventyConfig.addFilter("slug", (str) => {
  if (!str) {
    return;
  }

  return slugify(str, {
    lower: true,
    strict: true,
    remove: /["]/g,
  });
});

Enable anchor links on content headings

Eleventy uses markdown-it for Markdown parsing, and shows a few options for configuring it in the 11ty docs.

There are several plugins you can add to extend markdown-it, but in this example we are adding anchor links to our content headings. We're also extending the idea from our slug update to update which characters are removed and replaced to create anchors.

Kudos to Nicolas Hoizey for the concise method of modifying the markdown-it-anchor behavior to add a wrapping div to assist in styling placement of the anchor symbol. And for raising the issue to improve the base behavior of this plugin.

The markdown-it-anchor plugin added three permalink output options to assist with accessibility. This snippet uses the linkInsideHeader option with a custom symbol and permalink render function, which produces output like the following that also adds a wrapping .heading-wrapper. I've also selected the aria-labelledby option to prevent the extra text showing up in RSS feeds and search engine results.

// npm install --save-dev markdown-it-anchor slugify
// Import prior to `module.exports` within `.eleventy.js`
const markdownIt = require("markdown-it");
const markdownItAnchor = require("markdown-it-anchor");
// If not already added from previous tip
const slugify = require("slugify");

const linkAfterHeader = markdownItAnchor.permalink.linkAfterHeader({
  class: "anchor",
  symbol: "<span hidden>#</span>",
  style: "aria-labelledby",
});
const markdownItAnchorOptions = {
  level: [1, 2, 3],
  slugify: (str) =>
    slugify(str, {
      lower: true,
      strict: true,
      remove: /["]/g,
    }),
  tabIndex: false,
  permalink(slug, opts, state, idx) {
    state.tokens.splice(
      idx,
      0,
      Object.assign(new state.Token("div_open", "div", 1), {
        // Add class "header-wrapper [h1 or h2 or h3]"
        attrs: [["class", `heading-wrapper ${state.tokens[idx].tag}`]],
        block: true,
      })
    );

    state.tokens.splice(
      idx + 4,
      0,
      Object.assign(new state.Token("div_close", "div", -1), {
        block: true,
      })
    );

    linkAfterHeader(slug, opts, state, idx + 1);
  },
};

/* Markdown Overrides */
let markdownLibrary = markdownIt({
  html: true,
}).use(markdownItAnchor, markdownItAnchorOptions);

// This is the part that tells 11ty to swap to our custom config
eleventyConfig.setLibrary("md", markdownLibrary);

Example output:

<div class="heading-wrapper h2">
  <h2 id="enable-anchor-links-on-content-headings">Enable anchor links on content headings</h2>
  <a
    class="tdbc-anchor"
    href="#enable-anchor-links-on-content-headings"
    aria-labelledby="enable-anchor-links-on-content-headings"
  >
    <span hidden>#</span>
  </a>
</div>

Why use hidden? Because RSS, search engine results, and "reader mode" will (usually) respect it and prevent those environments from showing the anchor symbol.

You'll want the following CSS or similar to handle showing the anchor link symbol on your website:

/* Make the '#' anchor visible on your site */
.anchor hidden {
  display: block;
}

11ty Date Shortcodes and Filters

2020-11-23T00:00:00Z

`year` Shortcode

Get the current year - super useful for copyright dates.

Usage: {% year %}

eleventyConfig.addShortcode("year", () => `${new Date().getFullYear()}`);

`postDate` Filter

Eleventy uses Luxon for dates, which is a lighter weight alternative to Moment (but made by Moment).

By importing DateTime from luxon you are provided a deep toolbox of date methods.

Since this is a filter, and you'll likely use it to pass {{ page.date | postDate }}, the format at that point is, ex: (Sun Dec 31 2017 18:00:00 GMT-0600 (Central Standard Time) which to Luxon is the JSDate format.

The output as shown will be Nov 23, 2020, or you can update it to another option referenced in the Luxon docs on DateTime.

// Import prior to `module.exports` within `.eleventy.js`
const { DateTime } = require("luxon");

eleventyConfig.addFilter("postDate", (dateObj) => {
  return DateTime.fromJSDate(dateObj).toLocaleString(DateTime.DATE_MED);
});

Email Generator

2020-11-14T00:00:00Z

Generate simple, responsive email templates, with inlined CSS on build.

Use the Sass theme setup to re-brand the default template, and use the frontmatter keys for flexibilty in the layout. Check out the README for additional tips on creating emails.

Create Your Emails

Plugin: Social Images

2020-11-01T00:00:00Z

Based on my tutorial, this package creates dynamic images sized for social media tags (particularly Twitter and Facebook) based on your available pages. Use one of the predefined color themes, or define your own style, template, or both to customize the layout (like the ones in use on 11ty Rocks).

Configure the CLI script to run after your Eleventy build, and by default images will be created in _site/previews/ as png images. Use the CLI options to define a custom outputDir and/or a custom imageDir.

Docs and Install

Eleventy Plugin Template

2020-10-31T00:00:00Z

Kickstart your 11ty plugin project with this template that includes a barebones 11ty build to test your functionality, and docs on how to test your plugin locally.

Also includes a boilerplate for your plugin README, and demonstrates setting up plugin config defaults.

Build Your Plugin

Create Your First Basic 11ty Website

2020-10-31T00:00:00Z

The following tutorial is based on a live stream I did with Eva on Twitch. If you prefer, you can watch the recording below, or read on for the step-by-step instructions for creating your first basic 11ty website.

Check out the final project on GitHub, and the deployed examply on Netlify.

Begin the Project

Open a new directory in your editor of choice, and then in your terminal do the following command to start a brand new project:

npm init -y

Then, install Eleventy. For a basic site like this, eleventy itself is our only dependency!

npm install @11ty/eleventy

Once the installs complete, open package.json and update the default scripts section to the following. This enables a start command to run 11ty with hot-reload, which is provided by Browsersync that comes bundled as part of 11ty's --serve directive.

  "scripts": {
    "start": "npx @11ty/eleventy --serve",
    "build": "npx @11ty/eleventy"
  },

Add Eleventy Config

Next, we want to begin our Eleventy config. This initial addition is completely optional, but we will be adding more items to this config later.

Create the file .eleventy.js at the root of the project.

Then, add the following as the contents.

module.exports = function (eleventyConfig) {
  return {
    dir: {
      input: "src",
      output: "public",
    },
  };
};

The first change here is setting the input directory to src - as in, the directory 11ty will watch for changes and use to build for production. Then, we change the output directory to public which means that's where our production-ready files for use by localhost and a hosting server will be published.

Create `.gitignore`

At this point, you may want to take a minute to setup your .gitignore if you will be using version control. At minimum, here are the contents for that:

# dependencies installed by npm
node_modules

# build artefacts
public

Run the Develop Server

We have our base in place, so let's try to run the project using our start command:

npm start

And... oops! You will get an error message: "Cannot GET /". That's because 11ty will literally only serve up what you give it. So, we first have to create an index file in our input directory, which we defined in .eleventyconfig would be called src.

Create the Site Index File

So, perform the following steps:

Create src/
Create src/index.md

If you like, add some content into the Markdown file.

Markdown is one of 11 available templating languages you can use to create your 11ty site. Check out the other options >

Then, refresh the browser page and you will see the content you just added or a blank page if you added no content.

However, Browsersync is not yet activating which is why you had to manually refresh. To understand why, trigger your browser's context menu to "View Source". As you'll see, there is no markup being rendered besides what's needed for the conversion of Markdown to HTML.

For Browsersync to run (and to keep inline with overall standards) we need to provide a way to generate what is often called the HTML5 boilerplate that includes <html>, <head>, and <body>. Once the rendered markup includes <head> then Browsersync will be injected and provide the hot-reload for future edits.

Troubleshooting tip - if Browsersync isn't working, this is a good sign that you've forgotten to supply the HTML boilerplate.

Create the `base` Layout

To resolve needing to provide the HTML5 boilerplate, we'll use 11ty's concept of layouts.

One of the expected 11ty directories is called _includes and it's where you can add layouts.

You may also be familiar with the concept of templates, or template partials, and you may also place those in _includes.

A common 11ty convention is to create this essential HTML structure within _includes/base.njk.

If you are in a code editor that supports Emmet, you can use the command html:5 to instantly populate it with the HTML5 boilerplate.

Then, we'll prepare this base.njk to start accepting some Frontmatter values that we will add to our content. First, we'll plan for a title value.

Since we've created this as a Nunjucks template file (.njk), we can use the double-curly format to access the title Frontmatter variable, like so: {{ title }}.

We'll add it to the <title> and create it as an <h1> within the <body>.

Finally, we need to designate where the body of the markdown file should go. This is available in the Eleventy global page variable of content. In order to allow rendering of any HTML tags from the page content, we also use the built-in filter called safe which is added after placing a pipe - | - character.

This makes our full base.njk the following, with a bit of extra HTML semantics:

<!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>
  <header>
    <h1>{{ title }}</h1>
  </header>
  <main>
    {{ content | safe }}
  </main>
</body>
</html>

Then, we will go back to index.md and create frontmatter to designate the title and also to designate the layout value so that this page uses our base.njk template:

---
title: My first page
layout: base.njk
---

You will have to manually refresh the page one last time so that it loads the updated markup. Then, additional edits will begin to be picked up by Browsersync. You can test this by modifying the value for the title.

Create the Blog

Next, we'll create a new content type for our blog. To do this, we'll create a new directory and a markdown file for our first post.

Create src/blog/
Create src/blog/my-first-post.md

Create the `post` Layout

Next, we'll create a dedicated layout to display our blog posts.

Back in the _includes directory, create post.njk with the following content:

<article>{{ content | safe}}</article>

Chain the `post` Layout to the `blog` Layout

We'll then use an Eleventy concept called "layout chaining". This will allow us to designate that the post layout should also inherit the base layout.

To do this, in post.njk add the following frontmatter:

---
layout: base.njk
---

At this point, you can try to visit the blog page in the browser. By default, 11ty will have created the page using the same structure as you used to organize it in your src directory. In other words, it will be located at http://localhost:8080/blog/my-first-post/.

However if you visit that, you should find that it's blank! Read on to learn why.

Create `blog` Directory Data File

The first reason that link shows a blank page is that we haven't designated that our new blog post should use the post layout.

Now, we could add this as frontmatter to every post as we've already learned about. But when you plan on having many files in the same directory inherit certain attributes such as the layout, we can instead create a directory data file.

The directory data file is expected to have the same name as the directory, and be formatted as JSON. So, create src/blog/blog.json and add the following:

{
  "layout": "post"
}

At this point, you may still see a blank page if you have not added any content into the blog post 😉 The other part we haven't added that our base template expects is frontmatter for the title, so go ahead and add that now based on what we've learned.

Once you've added both a title and some content, on save you should nearly instantly see Browsersync update the page and see that content rendered.

Optional: Modify the Blog Post Permalinks

One other way we can use our directory data file is to set an altered permalink structure. "Permalink" is the term for the URL path that follows your domain (maybe you've also heard this called a "slug").

Just as an example, let's use the 11ty supplied page variable of fileSlug and tell 11ty to drop the blog/ from the front of the URL and just use the file name as the permalink value. Here is the update ot our src/blog/blog.json file:

{
  "layout": "post",
  "permalink": "/{{ page.fileSlug }}/"
}

So, our previous blog page is now available at http://localhost:8080/my-first-post/.

Note: You will continue to be able to visit the old URL because it is currently cached in the public directory. You can delete the public directory to remove it, because that directory is completely rebuilt after each save when 11ty is in watch mode.

Create `posts` Collection Via `tags`

Next, we'll explore an 11ty idea called collections. Collections are groups of related content created by adding tags.

We'll again make use of our directory data file and add a new key of tags with the value posts:

{
  "layout": "post",
  "permalink": "/{{ page.fileSlug }}/",
  "tags": "posts"
}

And with that, 11ty will now have created a collection called "posts" which we'll learn how to display next!

Before you move on, it would be useful to create a second blog post to help see the effects of our next few steps on affecting the posts collection. You can simply duplicate the first post and change the file name and the title frontmatter value.

Display `posts` Collection on Home Page

Often it is nice to display a list of your posts. Some times that's on the home page, and sometimes on an archive page. We will be adding it to our home page as a starting point, but you can customize this to display on any page.

Re-open index.md and add the following, then we'll review what's happening:

## Blog Posts

{% for post in collections.posts %}
{{ post.data.title }}
{% endfor %}

If you're wondering what those curly braces and percent signs are about, what we've done is created a for loop using the Liquid templating language (which happens to share this basic curly brace syntax with Nunjucks templating language).

We've defined a local variable of post to be the reference to an individual item in collections.posts. Thanks to adding our tag of posts, this collection was created by 11ty and is available throughout all site files.

Within the loop, we are simply retrieving the post's title, which is nested within data due to it being a frontmatter value.

Notice that the loop start and end uses the syntax of a single curly brace and a percent sign, while the portion retrieving the frontmatter variable is flanked by two curly braces. For both Liquid and Nunjucks templating, {% %} contains functions and {{ }} displays variables.

Create Linked List of Posts

We can modify our for loop to use semantic HTML and create a list of links to each post.

We've added one new variable, which is url. This is a page variable provided by 11ty for any paged piece of content, and so is available directly off of our local loop variable of post:

<ul>
{% for post in collections.posts %}
<li><a href="{{ post.url }}">{{ post.data.title }}</a></li>
{% endfor %}
</ul>

Have you realized we're doing all of this is a markdown file so far? That's right - we've mixed markdown, HTML, and Liquid and still had success rendering our outcome! This is part of the ✨ magic of 11ty!

If the previous example broke, it may be because you added spaces or tabs to indent and format the HTML - that's a pitfall of trying to mix templating languages which we'll sort out next!

Create Template Include from Blog Post Links

Ok, while we can do all of this in markdown, it's not sustainable for all types of content - or, as noted, breaks when trying to add formatting to the HTML (read why on the 11ty docs).

Let's improve our solution, first by creating a template include (or "partial") to hold our post list. Includes will live in our - you guessed it! - _includes directory.

Create _includes/postlist.njk, and move the HTML with the for loop into it, removing it from the index.

In it's place in index.md, add {% include "postlist.njk" %} and save.

Oops! We've hit an error which should be visible in your Terminal. Let's find out why...

Instruct 11ty How to Handle Template Processing

While we can do some template mixing, sometimes 11ty needs a little hint on our expectations of how to process the mix.

In the case of mixing templating with markdown, 11ty only allows either Liquid or Nunjucks.

What happened to cause our error had to do with order of operations, and in this case we need to add an 11ty-supplied frontmatter key to tell 11ty which order to process the templating vs. the markdown.

Add templateEngineOverride: njk,md to index.md frontmatter, which says to process the Nunjucks include first and then continue processing the markdown to render.

Hooray! The error is resolved, and we can again see our postlist being rendered on the home page.

Create a CSS File

One big thing missing from our site is some style 😎

CSS is not yet a file type recognized for auto-inclusion in the build directory, so we need to do a few extra steps.

First, let's create a very basic starting point for our CSS.

Create src/css/style.css, and add:

body {
  font-family: sans-serif;
}

Passthrough CSS

In order for 11ty to recognize our CSS file and include it in the build directory, we need to modify .eleventy.js.

As the first line inside of the module.exports function (before the return we had previously added), add:

eleventyConfig.addPassthroughCopy("./src/css");

This tells 11ty to "pass through" the CSS directory.

Watch CSS for Changes

In addition to the pass through, we also need to ask 11ty to watch the CSS directory for changes so that when we modify our CSS file it triggers a rebuild and refresh from Browsersync.

Still in .eleventy.js, add the following after our pass through line:

eleventyConfig.addWatchTarget("./src/css/");

When changes are made to .eleventy.js, it typically requires stopping the watch process and restarting. On both Mac and PC, use Ctrl + C in Terminal to stop the watch command, and then re-run npm start to start it again. When complete, the CSS directory should be present in public and if you test modifying style.css the changes should cause a rebuild and be updated in public/css/style.css.

Link to Stylesheet in `base` Layout

Now, our CSS hasn't updated our site to a sans-serif font yet. Any guesses why?

Yup - we need to add the stylesheet link to our layout!

Within _includes/base.njk, add the following within the <head> section after the <title>:

<link rel="stylesheet" href="/css/style.css" />

And on save, once Browsersync refreshes, the page content should be using a sans-serif font.

🏁 Checkpoint: You have now created a successful 11ty starting point! Using what you've learned so far, you can continue making different content types and organizing them into collections. You know how to modify their permalinks, and chain layouts. And you know how to use Liquid and Nunjucks to display variables and leverage for loops. You can also mix templating languages and overcome templating pitfalls. And you can add and watch a CSS file. The last few sections show a bit more advanced features of 11ty that will help you take your project further!

Custom Data

One of my favorite features of 11ty is custom data. One of the expected directories in the 11ty file system is _data, and any files you create here that are module.exports or basic JSON data is made availably globally to your pages and layouts.

So, let's create a simple (and silly) data file: src/_data/facts.json

[
  "Did you know horses can swim?",
  "Did you know that the average human can hold their breath for 2 minutes?",
  "Did you know that we live on Earth?"
]

These are definitely true facts...maybe...

Add `facts` Loop to `post` Layout

For fun, let's add our facts after our blog post content.

Add the following after article in _includes/post.njk:

<aside>
  {% for fact in facts %}
    <p>{{ fact }}</p>
  {% endfor %}
</aside>

This for loop should look pretty familiar, but instead of retrieving data from a collection we are requesting it from our facts. Recall that I mentioned that the output of files in _data is made globally available? This means that we can access the output of that data by referencing the filename, which is where facts comes from.

If you visit one of your blog posts, you should see each fact is output within a paragraph tag.

Create `randomItem` Filter

Now, it's not very interesting to output all of our facts at once.

Let's add our first custom filter to help randomly pick one of the facts to display.

Open .eleventy.js, and add the following between the work related to our CSS, and the return:

eleventyConfig.addFilter("randomItem", (arr) => {
  arr.sort(() => {
    return 0.5 - Math.random();
  });
  return arr.slice(0, 1);
});

addFilter globally makes the "randomItem" filter available to any templating language. In this case, we expect that the data that will come into the filter will be an array, since we'll be using it on our facts array. The body of the filter is a very basic randomizing function written in JavaScript.

Add the Filter to `facts` Loop

Back in our post layout, we'll update our for loop to include our filter. If you recall from applying the safe filter, a filter goes after the variable or collection it is being applied to, with a pipe | character inbetween. The facts array is passed into the filter for processing.

{% for fact in facts | randomItem %}

On save, there should only be one randomly selected fact displayed on each blog post. Of course, there's a chance that the fact will be the same since it's a small pool to choose from ☺️

Important note: Since 11ty is a truly static site builder, the quote will be selected during build time and not on page load. This is an important difference from dynamic build tools like Gatsby. You can include JavaScript on your own to make this selection happen on page load, but using the filter method makes it part of the build process. If you have content that you want to update somewhere between statically and page load, you can use tools like IFTTT to trigger periodic builds if your site host supports webhooks.

Create Data from API

11ty can use the output of Node modules as data, which also means we can use Node packages to help us retrieve data. And it means we can get external data at build time.

Let's explore this by retrieving a cat picture from an API using axios for fetching.

Create _data/catpic.js, and add the following:

const axios = require("axios");

module.exports = async () => {
  const result = await axios.get("https://aws.random.cat/meow");

  return result.data.file;
};

Note: You may need to add axios to your package for a local build to work: npm install axios

It's ok if you're not very familiar with Node! What we're doing here is fetching the result from the cat pic API. Then we are returning the file key that is present in that particular data set.

Add `catpic` to Home Page

Now we'd like to display the retrieved cat pic on our home page. Add the following to index.md:

## Cat of the Day

<img src="{{ catpic }}" />

Since the API includes an image URL within the file key, and we are directly returning that value out of our function within _data/catpic.js, and 11ty has made that output available globally via the filename - this makes including it in our image tag very simple!

Once again, remember that this fetch only happens at build time. Meaning, once your site is built on your hosting server, whatever cat pic is retrieved will be what is displayed until the next site build. However, for the duration that you are doing local development with npm start, a new build is generated each time you save a file, which will make it appear as though the catpic is changing more frequently.

🏁 Checkpoint: Congrats! You now know how to add local and external data to your 11ty site! With these fundamental concepts, you can really stretch 11ty to many use cases. To wrap up, read on to learn how to deploy to Netlify, or feel free to use the host of your choice.

Bonus: Deploy to Netlify

Netlify is an excellent host for static sites - especially because you can start and stay free for basic needs.

Create a Netlify Config

If you choose to continue with hosting on Netlify, we can create a file to speed up your first deploy.

At the root of your project (outside of src), create netlify.toml with the following content:

[build]
  # Directory (relative to root of your repo) that contains the deploy-ready
  # HTML files and assets generated by the build. If a base directory has
  # been specified, include it in the publish directory path.
  publish = "public"

  # Default build command.
  command = "npm run build"

This is telling Netlify that our production-ready files post-11ty build will be located in public/ and that the command to produce that build is npm run build.

Push to Github

Netlify runs off of a continuous integration model, which allows any pushes to your main branch on Github to trigger a build.

Alternatively, you can drag and drop your site folder to deploy!

For the GitHub route, create a repo and push your project to Github (instructions outside the scope of these steps).

Connect to Netlify and Deploy

After pushing to GitHub, follow these steps, after which your new site will be live immediately at a temporary URL provided by Netlify!

Create a Netlify account, using GitHub login for fastest deploy
Select "Create from Git"
Link to Github and select your repo
Netlify will recognize the values in netlify.toml and you can deploy! 🎉

Next Steps: For a video walkthrough and slightly different way to get started with 11ty, including adding Sass for styling, check out my 20 minute egghead course: Build an Eleventy Site From Scratch

Plugin: Emoji Read Time

2020-10-20T00:00:00Z

This plugin provides a filter that displays an estimated read time for Eleventy content, optionally with an emoji visual indicator.

The plugin offers config options to change or remove the emoji, update the word-per-minute, and alter the label. A simple string is returned, so the text formatting is up to you.

The default appearance displays one 🍿 per rounded 5 minutes of estimated reading time, ex: 🍿 7 min. read

Docs for Emoji Read Time

Build a Community Site With Eleventy

2020-10-20T00:00:00Z

Based on my experience building StyleStage.dev, this tutorial will cover how to create a full-featured 11ty site including:

How to initialize Eleventy and create useful develop and build scripts
Recommended setup customizations
How to define custom data and combine multiple data sources
Creating layouts with Nunjucks and Eleventy layout chaining
Deploying to Netlify

Build Your Community

11ty Web Component Generator

2020-10-20T00:00:00Z

Eleventy makes it possible to mix templating languages. More importantly to this generator is that we can customize the output file type and composite a file from includes.

This generator works with the inherent features of 11ty. Web components are generated within a Nunjucks (.njk) template that outputs the final .js file.

Demo the Generator

11ty Sass Skeleton Starter

2020-10-20T00:00:00Z

Featuring absolutely nothing beyond a base HTML5 template and the essential setup to watch and compile your Sass alongside 11ty.

Includes minifiying and autoprefixing of styles postbuild.

Get the Starter

11ty Netlify Jumpstart

2020-10-20T00:00:00Z

Quickly launch an 11ty-generated static site. Includes a minimal Sass framework, and generated sitemap, RSS feed, and social share preview images.

Test Drive the Jumpstart

Build an Eleventy Site from Scratch

2020-10-20T00:00:00Z

Build a site in 20 mins! Start from a blank project and build up to an 11ty site that includes Sass, a blog collection, and is prepared to source content from a headless CMS.

Watch the Collection

Plugin: Open in CodePen

2020-04-02T00:00:00Z

This plugin provides an Eleventy shortcode to add "Open in CodePen" functionality for code demos.

The functionality pairs well with the result of this tutorial on creating live static code demos.

Docs for Open in CodePen

11ty Rocks!

Smart Incremental Rebuilds With eleventyImport

Using eleventyImport

When will templates rebuild?

Beware of circular imports

Process CSS or Sass With LightningCSS

Custom Template Languages in Eleventy

Adding Sass Support

Important: Exclude Custom Template Files from all Collection

Autoprefixing and Minification with LightningCSS

Process with LightningCSS Only, No Sass

Plugin or Manual Include?

Plugin: Collection Schemas

Eleventy Collection Schemas

Introducing: Collection Schemas

How collection schemas work

Schema Limitations

Plugin: Sass + LightningCSS

11ty Membership Site

Building A Membership Site With 11ty

Prerequisites

How it works

Authentication Flow

Assigning routes to Edge functions

Members-Only Content Flow

Authoring premium content

Next steps and resources

11ty Community Links: January 2023

New Features and Upgrade Considerations for Eleventy v2.0.0

Major Feature Additions

Eleventy Edge

WebC

Breaking Changes

Configuration, Build, and Serve

Custom Data and Data Cascade

Collections, Filters, and Shortcodes

Content Creation

Upgrading to v2.0.0

What You Missed From v1.0.0

Understanding WebC Features and Concepts

Including WebC components outside of .webc templates

Static HTML WebC rendering vs. web component rendering

WebC for static HTML

WebC for web components

Styling for custom elements and web components

Data within WebC components

Unique values using uid

Concatenating strings

Privatising attributes

Removing unnecessary elements

Advanced patterns with slots

Introduction to WebC

WebC in a nutshell

Single file components

Custom elements in WebC output

Asset bundling

Scoped styles

Slots

WebC for web components

Learn more about WebC

Ignore Eleventy Files With Environment Variables

Step one: Include environment variables

Step Two: Ignore files from within the Eleventy config

Creating and Using Eleventy Collections

What Are Collections?

Creating Collections

Collections From tags

Assigning tags to many templates

Display Collection Data

More Ways to Create Collections With addCollection

Group Tags Together

Glob By File Type

Collections From Template Front Matter Data

Collections From Local Data

The all Collection

Filtered vs. Unique Collections

Exclude Content From Collections

Summary of Collection Creation Methods

Filter Titles for RSS and Social Shares

Step 1: Creating the Filter

Using `eleventyImport`

Important: Exclude Custom Template Files from `all` Collection

Including WebC components outside of `.webc` templates

Unique values using `uid`

Collections From `tags`

More Ways to Create Collections With `addCollection`

The `all` Collection

Ordering and Output of the `demos` Collection