Connect with us

Technology

A Deep Dive Into Eleventy Static Web site Generator — Smashing Journal


About The Writer

Stephanie Eckles is a front-end centered SWE at Microsoft. She’s additionally the creator of ModernCSS.dev which offers fashionable options to previous CSS issues as in-depth …
Extra about
Stephanie

Eleventy (aka 11ty) is rising within the ranks amongst static web site mills. This Node-based builder is enticing attributable to its zero-config place to begin, purely static output, and ease of reaching the coveted prime Lighthouse efficiency rating of 4 excellent 100s. Let’s dive into what else makes it distinctive, and find out about some important ideas that can assist you efficiently get began.

However first — let’s rapidly evaluation what is supposed by a “static web site” after which what a generator offers. A static web site consists of static content material — as in, the HTML, CSS, property, and all content material are already compiled collectively earlier than pushing to an internet site host. That is totally different from a dynamic web site that compiles these issues from querying a database at run time (like WordPress) or that pulls content material from APIs client-side (like JavaScript frameworks with out server-side rendering).

A static web site generator is an surroundings and construct processor to compile your content material into static HTML. They often provide helpers to supply flexibility in writing your content material (like supporting Markdown) and embrace strategies for templating. So as a substitute of writing HTML pages one after the other and having to repeat and paste the repeated elements, a generator will help breaking these issues into elements by way of a sure templating language. Then the generator’s construct course of will deliver every thing collectively and output the ultimate HTML that may be uploaded to an online host to be served as your web site. Relying on the net host you utilize, this construct course of may even be carried out by the host.

There are a lot of static web site mills obtainable. You’ll have heard of and even used ones like Jekyll, Hugo, Gatsby, Subsequent and Nuxt. A complete record is supplied by Jamstack.org.

What Makes Eleventy Totally different From Different Static Web site Mills?

Eleventy is exceptionally quick each throughout builds and within the browser. That is largely due to not requiring the loading of a client-side JavaScript bundle so as to serve content material (in comparison with one thing like Gatsby). Server-side rendering isn’t even a priority right here, because the filesystem web page creation defaults to static HTML.

What actually makes Eleventy distinctive is the power to pick from and intermix as much as ten totally different templating languages:

A screenshot from the 11ty.dev documentation listing the available templating languages including HTML, Markdown, JavaScript, Liquid, Nunjucks Handlebars, Mustache, EJS, Haml, and Pug.
A screenshot from the 11ty.dev documentation itemizing the obtainable templating languages together with HTML, Markdown, JavaScript, Liquid, Nunjucks Handlebars, Mustache, EJS, Haml, and Pug. (Giant preview)

Intermixing languages can occur in the identical file, or between layouts. For instance, I typically write my predominant content material with Markdown that feeds right into a Nunjucks structure. In some initiatives, I’ve discovered it helpful to have the ability to loop over some information utilizing Nunjucks whereas within the Markdown file. This capability to mix languages may be very highly effective, and lets you design a write-and-build workflow that works greatest for you and your mission.

Eleventy features a --serve flag that makes use of BrowserSync to allow serving the positioning domestically and with hot-reload upon file adjustments. This can be a nice comfort, and is sweet to bear in mind in the event you’re not in search of a static web site generator however maybe an improve from construct instruments like Gulp.

As a part of being zero-config, all of your web site information might stay within the root of your mission. To change the enter and output directories, you possibly can create an Eleventy config, which is anticipated to be a root file known as .eleventy.js. Right here’s a fast snippet exhibiting methods to make this modification:

module.exports = perform (eleventyConfig) {
  return {
    dir: {
      // default: [site root]
      enter: "src",
      // default: _site
      output: "public",
    },
  };
};

As famous earlier, the default habits is filesystem web page creation which is usually of nice profit particularly for quickly getting began. That is simply overrideable by assigning a customized permalink and that may be carried out per file, for a whole listing, or dynamically for a set of knowledge. Permalinks additionally provide one other superpower which we’ll discover in a bit!

Uniquely, throughout the construct, you possibly can put together content material, information, and transforms on that content material and information through the use of JavaScript and leveraging filters and shortcodes (we’ll discuss these later). Once more, this all occurs with out including a JavaScript bundle client-side, whereas nonetheless enabling using JavaScript as a templating language.

Vital Notice: You’ll be able to efficiently use Eleventy with no or low JavaScript information.

Not like different SSGs like Gatsby, or environments like WordPress, most Eleventy websites don’t require any plugins. There are some plugins obtainable, however they don’t seem to be obligatory for important performance.

When constructing with Eleventy, you possibly can add on options as you want them. In reality, you might simply use HTML and by no means work with any of the opposite templating languages. Eleventy is simply as complicated as your mission requires!

Understanding Important Eleventy Ideas

Let’s go over just a few bits of terminology and ideas that can show you how to achieve success in creating your Eleventy initiatives.

Layouts And Templates

You could consider these phrases as interchangeable, however in Eleventy’s context, they do have contextual meanings:

  • Template is the generic time period for all content material information.
  • Layouts are particular templates that wrap different content material.

For instance, template refers to all of your Markdown information, whereas a structure is likely to be a Nunjucks file that incorporates the HTML5 boilerplate and a slot for the template content material. We’ll learn to make this work within the part on getting began.

Filters And Shortcodes

These are extra methods to change content material output, and create reusable template elements. They’re obtainable to be used with Nunjucks, Liquid, Handlebars, and JavaScript templating. Filters and shortcodes are outlined inside .eleventy.js.

Past variables and operators obtainable in your templating language of alternative, Eleventy has unified the idea of filters throughout the beforehand listed languages. Filters remodel content material indirectly particular to the content material kind. For instance, you might create a filter meant for strings to uppercase them. Otherwise you might need a filter meant for use on arrays to change what’s returned, like selecting a random merchandise. Some filters are supplied by Eleventy, just a few of which we’ll use within the getting began tutorial.

Shortcodes enable creating reusable template elements and are capable of settle for arguments. They are often both standalone or paired, which means they wrap content material with a begin and finish tag.

One among my favourite shortcodes is to render the present yr — which means no extra outdated copyright years in your footer! Right here’s methods to create a yr shortcode:

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

To make use of it in a Nunjucks or Liquid template seems like this: {% yr %}.

You’ll be able to evaluation the Eleventy docs for examples of paired shortcodes.

Collections

Collections are teams of associated content material, and are usually created inside frontmatter by defining tags. Tag syntax choices embrace single strings, single-line arrays — ["tagA", "tagB"] — for multiples, or YAML-style lists to assign a number of tags. For instance, I can create a “pages” assortment by including the next frontmatter to all content material I wish to be included in that assortment:

---
tags: pages
---

After you have outlined a group, you possibly can entry it by way of your templating language of alternative inside the international collections object. To entry our “pages” assortment would appear like collections.pages. This returns an array of that assortment’s information, and so you possibly can carry out array operations like looping over it comparable to to provide a listing of hyperlinks or article teaser playing cards. You’ll be able to even suppress regular file output and use solely collections to handle information show, which is beneficial for managing single-page web site content material.

Customized Knowledge

Thus far we’ve talked about creating content material as information, however Eleventy additionally makes it very simple to take care of totally different information sources. That is known as “customized information” and lives as JavaScript module exports or JSON information within the _data listing.

Customized information can be utilized to:

  • Outline a primary JSON array.
  • Return the outcomes of a fetch operation.
  • Retrieve and re-format content material from a headless CMS.

Eleventy makes all information from inside _data obtainable below a variable matching the filename. For instance, if I create posts.json then I can entry that in my templates as posts. Utilizing Nunjucks, right here’s an instance of looping over the posts information:

{% for put up in posts %}
  {{ put up.title }}
{% endfor %}

Pagination And Creating Pages From Knowledge

In Eleventy phrases, pagination refers to iterating over a knowledge set and defining a template for the output of that information “chunk”. That is carried out with a devoted file that defines the pagination inside frontmatter. The file additionally contains organising your meant output for the information, which means it turns into its personal template as properly. We are able to outline a structure to ship the content material to and likewise add tags to create a group for ease of reference and adaptability for the output.

Notice: For those who use customized information to retrieve content material from a CMS, then pagination is the Eleventy technique you’re in search of to show that information into pages dynamically.

Right here’s an instance of referencing our posts customized information which we’ll assume we’re retrieving by way of a fetch from a headless CMS. Importantly, the measurement is ready to 1, which suggests every “pagination chunk” ought to produce one single web page of output. We then use the alias to create a reference to the present merchandise within the pagination loop, after which use that reference within the permalink definition and the template physique.

The file that defines the pagination can stay wherever you’d like inside your enter listing. My organizational desire is to create a generate listing, after which identify it the identical as the gathering will probably be creating. Think about the next to be src/generate/posts.njk:

---
pagination:
  information: posts
  measurement: 1
  alias: put up
  addAllPagesToCollections: true
permalink: "/{ slug }/"
tags: posts
structure: put up
templateEngineOverride: njk, md
---
{ protected }

On this case, the permalink is assigning the web page to be output straight off of the positioning root. You might change this so as to add a prefix comparable to /posts/{ slug }, for instance.

Moreover, if you would like the entire generated pages to be obtainable within the assortment created by the tags, you will need to set addAllPagesToCollections to true to incorporate greater than the primary merchandise.

Lastly, in case your content material is coming in as Markdown as a substitute of pre-compiled HTML, you’ll want to make use of the templateEngineOverride. Within the instance snippet, I’ve set it to njk, md which suggests the template content material will must be processed each as Nunjucks so as to convert the variable, after which Markdown to compile the contents returned within the variable.

For those who’re questioning what protected means, we’re going to study that subsequent!

How To Get Began With Eleventy

Alright, so that you’re able to get going together with your first Eleventy mission! This transient tutorial will show you how to get a beginning construction in place to proceed constructing from. We’ll use the ideas we’ve already discovered about and add just a few new concepts, too.

The primary vital word right here is that Eleventy is a scoped package deal, so right here’s the set up command:

npm set up @11ty/eleventy

Subsequent, a useful comfort I love to do is add the next scripts into my package deal.json:

"scripts": {
  "begin": "eleventy --serve",
  "construct": "eleventy"
}

As talked about beforehand, the --serve flag will allow a neighborhood server by way of BrowserSync.

My desire is to replace the enter/output directories as we already checked out, so now it’s time to create some content material inside src or the enter listing of your selecting.

With a view to put together our mission to be extra versatile and scalable from the beginning, I’d recommend creating not less than one structure that incorporates the HTML5 boilerplate. Layouts must be outlined inside a straight known as _includes, which is one among a handful of anticipated directories.

A conference that you simply’ll typically discover amongst starters is to name this structure base. I’ve a desire for making it a Nunjucks file.

Right here’s a pattern base.njk:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta identify="viewport" content material="width=device-width, initial-scale=1.0">
  <title>{{ title }}</title>
</head>
<physique>
  <header>
    <h1>{{ title }}</h1>
  </header>
  <predominant>
    { protected }
  </predominant>
</physique>
</html>

The double curly braces are Nunjucks syntax for variables. Right here, we’ve ready for an incoming title variable that can shortly be provided by way of entrance matter. The content material variable is supplied by Eleventy and marks the slot the place all incoming non-front matter content material ought to go. Importantly, that is used along side the supplied protected filter which prevents compiled HTML from being escaped versus rendered.

Now it’s time to create our web site index, which we’ll add as index.md:

---
title: Hi there Smashing Readers!
structure: base.njk
---

Thanks for studying — hope you’re excited to attempt Eleventy!

Discover that within the entrance matter we added our title, and likewise outlined the structure.

At this level, we will run our mission with the script we added: npm begin. It will set off BrowserSync to setup localhost:8080 (if it’s obtainable) however you will want to manually open it within the browser. Try this fast tip in the event you’d prefer it to open the browser routinely.

The final important step is so as to add a stylesheet. Presently, CSS isn’t acknowledged as an routinely included filetype so we’ll have one further config step after we create our stylesheet.

You’ll be able to add a CSS file wherever you’d like in your enter listing, comparable to css/fashion.css. Then, open .eleventy.js (or create it within the mission root in the event you didn’t do the enter/output customization) and add the next :

module.exports = perform (eleventyConfig) {
  eleventyConfig.addPassthroughCopy("./src/css/");
  eleventyConfig.addWatchTarget("./src/css/");

  // - enter/output customization if utilizing -
};

First, we add the css listing as a “passthrough copy” which suggests Eleventy ought to embrace it within the push to the output listing. Then we additionally add it as a “watch goal” in order that as we make adjustments to our kinds whereas operating our begin command, Eleventy will set off a rebuild to replace our native web site.

Lastly, we have to bear in mind so as to add the hyperlink to our stylesheet inside our base structure:

<hyperlink rel="stylesheet" href="https://smashingmagazine.com/2021/03/eleventy-static-site-generator/{ url }" />

Once we outline the stylesheet’s location, we cross it by means of Eleventy’s url filter which can regulate the relative file path as wanted upon construct.

Subsequent, let’s create a “pages” put up kind to discover utilizing collections and layouts a bit extra. To do that, add the listing of pages and create one or two Markdown information, together with a title front-matter key however not a structure.

We’re going to make use of a barely totally different technique to outline the structure this time — a information listing file. This file is usually formatted as JSON and allows us so as to add information that needs to be utilized to all information inside a listing, which prevents having to duplicate it throughout information. The file must be named the identical because the listing will probably be used for, so create the file pages.json and add the next content material:

{
  "structure": "web page.njk",
  "tags": "pages"
}

We’ve additionally gone forward and outlined tags so as to create the “pages” assortment. However the structure we outlined doesn’t really exist but, so create _includes/web page.njk and add the next:

---
structure: base.njk
---

<article>
  { protected }
</article>

Right here we’re utilizing the Eleventy idea of structure chaining to have the ability to re-use our base template but additionally add a novel component for our web page structure, which is the <article>. Which means the entire content material of our pages will use each the web page structure and base layouts.

Format chaining reduces duplication by permitting re-use of boilerplates and base web site structure buildings.

Now that we’ve created content material for the pages content material kind and outlined it because the “pages” assortment by way of the tags, let’s see how we will entry that assortment. Right here, we’ll use Nunjucks to loop over the gathering and output a listing of hyperlinks to every web page. This loop will likely be added inside our index.md file.

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

We’ve carried out one thing distinctive although which is that the inside of the loop really switches again to Markdown to render the hyperlinks. This isn’t a required technique to deal with this situation, however it may be very useful! Typically, relying on complexity, this may occasionally not work. The true cause is that the Markdown renderer defaults to Liquid templating language, so in the event you’re utilizing Nunjucks options past primary loops, you’ll have to let Eleventy know methods to course of the file.

Within the earlier part on pagination, we really already appeared on the resolution for this. And that’s to utilize the templateEngineOverride to point that the file needs to be processed as each Nunjucks and Markdown. The next full resolution needs to be positioned within the template’s entrance matter: templateEngineOverride: njk, md.

At this level, you’ve created a primary multi-page web site! When you have want of utilizing exterior information, leap again as much as the part on pagination.

Different Methods To Begin An Eleventy Mission

Whereas another static web site mills and environments like WordPress have the idea of “themes”, Eleventy makes use of the time period “starter”. There’s a rising assortment to select from, and plenty of could be discovered within the itemizing inside the Eleventy docs.

My desire is to make use of Sass with my Eleventy initiatives, and I’ve a Sass starter obtainable in the event you’d prefer to see methods to add that into your construct course of. Others could select so as to add in Gulp if they’re used to that construct pipeline for property and processing.

I’ve additionally created a minimal starter that features the options mentioned on this article and shares similarities with the tutorial consequence. It additionally has a small instance of fetching exterior information, and reveals methods to add in a a fan of show web site navigation based mostly on a group.

Increasing On The Fundamentals

When you’ve experimented with creating your first web site with some primary content material and perhaps some customized information, it’s useful to know extra methods to work with that content material. Here’s a transient overview of another ideas to pay attention to.

I discussed earlier that permalinks have a superpower. And that’s that you need to use them to output non-HTML file sorts.

Two helpful examples are creating an RSS feed and a sitemap, each of which occur to usually be XML information. What’s actually highly effective is that you would be able to proceed to make use of the templating language of your alternative to assist generate these information, so you possibly can loop over web page information with Nunjucks to maintain your RSS feed recent, for instance.

Customizing Collections

Typically utilizing tags to create collections might not be ample. Or, you might wish to create filtered variations of an present assortment. We are able to alter or create collections through the use of a sequence of supplied features. These will stay within the .eleventy.js config file.

On this instance, we’re utilizing the addCollection perform to filter objects in an present assortment. The brand new assortment will likely be based mostly on the existence of customKey inside entrance matter. This key’s returned off of the information object which is hooked up to all generated Eleventy content material.

eleventyConfig.addCollection("specialCollection", perform (assortment) {
  return assortment.getAll().filter((put up) => put up.information.customKey);
});

You’ll be able to evaluation different methods to create, modify, and use collections within the Eleventy docs.

Working With The Knowledge Cascade

Eleventy has a extra full idea of how information is compiled for a template known as the information cascade which we solely simply started exploring on this information. You’re going to get probably the most out of Eleventy in the event you evaluation how that works, beginning within the docs. Ben Myers additionally has a superb information to understanding the information cascade.

Within the intro, I briefly talked about there have been plugins obtainable, however that they aren’t all the time wanted. Nonetheless, there are just a few I have a tendency to make use of on most initiatives, which embrace:

  • @11ty/eleventy-plugin-rss
    If you want to have an RSS feed, this official plugin offers some filters that can assist you to generate the feed. The linked repo features a pattern feed, which you may additionally discover in use inside some starters.
  • @11ty/eleventy-plugin-syntaxhighlight
    As an alternative of loading Prism as a script for code highlighting, this plugin permits that processing to be utilized as a part of the Eleventy construct course of. This implies code blocks are reworked to incorporate the lessons for making use of a Prism theme forward of time, so you’ll solely want so as to add a Prism CSS theme of your alternative.
  • @11tyrocks/eleventy-plugin-social-images
    A characteristic I sought out early in my Eleventy exploration was the power to generate social media share photographs. This led me to create a plugin that makes use of Puppeteer behind the scenes to take the snapshot. The plugin comes with prebuilt templates in addition to config choices to outline your individual template file.

I’d additionally suggest changing into accustomed to the remainder of the official Eleventy plugins as they deal with different widespread wants together with navigation and picture dealing with.

Deciding If Eleventy Is Proper For Your Mission

Eleventy, like most static websites, is greatest for content material that doesn’t usually must be served dynamically or on-demand. This isn’t to say all of the positioning needs to be static, or that there aren’t methods to make content material dynamic. You should still load JavaScript to allow dynamic content material like fetching from APIs or creating interactive widgets. It’s also possible to use providers like IFTTT or Zapier to facilitate rebuilding your web site in case your host helps construct webhooks and you’ve got elements that you simply wish to refresh on a schedule.

Due to customized information and pagination, we noticed it was simple to incorporate exterior information as from a headless CMS or every other API. So though will probably be served statically, you continue to have a number of flexibility in the place you pull content material and the way you handle it.

My favourite factor about Eleventy is that it doesn’t impose many opinions on how I ought to construction my web site, past the few anticipated directories we talked about for _includes and _data (and you’ll replace the naming conference of these, too). This can be useful if you’re trying to migrate a web site and with the ability to probably transfer some present file construction as properly. Nonetheless, in the event you want a extra opinionated structure, you would possibly search a special possibility.

I additionally take pleasure in how I can mould Eleventy to suit my psychological mannequin for a given mission by leveraging a number of templating languages in addition to filters, shortcodes, and layouts. Starters additionally assist give a lift in an effort to give attention to what’s actually vital: your content material. And the excessive efficiency of purely static output can be an incredible profit.

For those who do want a bit extra in your construct course of, you possibly can add different acquainted instruments like Webpack, Gulp, or Parcel. You could possibly discover a starter that already contains these issues. Bear in mind you too can leverage Node scripts that are already inherent to the Eleventy construct course of.

Eleventy may be very able to dealing with giant quantities of web page era. It has been used for some giant and complicated websites comparable to Google’s internet.dev and Netlify’s advertising web site. I’ve additionally used Eleventy for some unconventional functions, like e-mail and internet part mills, together with some others that are described on this overview.

Extra Assets

I hope this information has each peaked your curiosity and ready you to start utilizing Eleventy! It included a number of factors that I discovered a bit difficult to uncover after I was creating my first mission with it. Since I first discovered Eleventy in April 2020, I’ve constructed over 20 Eleventy initiatives counting starters, plugins, aspect initiatives, and course supplies. A lot of these could be discovered on my web site 11ty.Rocks which additionally has tutorials and ideas. Eleventy is one thing I actually take pleasure in discussing, so be at liberty to achieve out on Twitter!

The next are extra sources for serving to you in your journey to study and get probably the most out of Eleventy:

Lastly, I wish to word that the Eleventy neighborhood is small however lively! For those who ever have issue discovering some info, you possibly can tweet your query to the official @eleven_ty account. Eleventy’s creator, Zach Leatherman, is fast to reply or RT questions to assist get you again in your means!

Smashing Editorial(vf, yk, il)



Click to comment

Leave a Reply

Your email address will not be published. Required fields are marked *