Two approaches to asset pipelines

As outlined by Max Bock in his infamous blogpost about asset pipelines, there are two main ways to transform your assets source files (SCSS and JS mainly) into production-ready output files.

1. Use external tools working in parallel with Eleventy
2. Use Eleventy to manage everything

Here is another nice blogpost by Vadim Makeev if you would rather like Eleventy to be in charge. As for me, I like the flexibility of an external build pipeline, mainly because I can easily use the same approach in non-Eleventy contexts.

My default solution is to use NPM scripts to compile assets directly to my output folder. Meanwhile, using a package like npm-run-all, I can have Eleventy do its thing. Running those processes in parallel is quite efficient and the separation of concerns appeals to me.

Previously, you could essentially go down three different routes with this external approach:

1. Use addWatchTarget in your configuration file to watch source files and trigger an Eleventy build when any file changes. Eleventy builds are fast, but triggering a whole build to reload my browser feels a bit wasteful. It also introduces a potential race condition between your external asset pipeline and Eleventy.
2. Generate compiled assets in a folder added to .gitignore as well as to Eleventy ignore rules and use addPassthroughCopy to copy those generated assets to the output folder. No Eleventy build is triggered but your assets are now written twice to disc, which also seems a bit awkward.
3. Use an external package like Browsersync as a local server to do the watching. Easy to manage via the CLI and the --files option allows you to watch your entire output directory to trigger browser reloads.

A native performant solution

With the 1.0 version of Eleventy Dev Server, I can now use a native and elegant solution.

I can keep building my assets with NPM scripts and run npx @11ty/eleventy --serve --quiet in parallel. The trick here is to use the new watch option in your config file to target the output directories used by your build process.

Any change to files in these directories will then trigger a server reload, even if those changes are the result of an external asset pipeline.

Here is a bare bones example of the scripts I use in development. You could use --watch flags with sass and esbuild instead of the onchange package but, again, I like the separation of concerns (and I also find it easier to read and understand).

"scripts": {
  "server": "npx @11ty/eleventy --serve --quiet",
  "styles:dev": "sass --embed-source-map --source-map-urls=\"absolute\" \"./src/assets/scss/main.scss\" \"./dist/assets/css/main.css\"",
  "scripts:dev": "esbuild \"./src/assets/js/main.js\" --target=es2020 --bundle --outfile=\"./dist/assets/js/main.bundle.js\"",
  "watch:scripts": "onchange \"./src/assets/js/**/*\" -- npm run scripts:dev",
  "watch:styles": "onchange \"./src/assets/scss/**/*\" -- npm run styles:dev",
  "dev": "npm-run-all --parallel server watch:*"
},

And here is the relevant portion of an Eleventy config file.

module.exports = function (eleventyConfig) {
  // ---------- other config options ----------

  // ignore source assets (processing and watching)
  eleventyConfig.ignores.add("./src/assets/**/*");
  eleventyConfig.watchIgnores.add("./src/assets/**/*");

  // pass through (copy fonts and images to output directory)
  eleventyConfig.addPassthroughCopy("./src/assets/img");
  eleventyConfig.addPassthroughCopy("./src/assets/fonts");

  // server config (watch generated assets in dist folder)
  eleventyConfig.setServerOptions({
    watch: ["./dist/assets/css/**/*.css", "./dist/assets/js/**/*.js"],
    port: 3000,
  });
};

That's all there is to it, really. This very website uses the approach outlined above. So far, I am very happy with it and plan to use it for all my other projects once Eleventy 2.0 comes out of beta.

Team Nunjucks

I personally use Nunjucks as my templating language with Eleventy. On top of being powerful and simple to learn, its syntax is similar to Twig, which I have been using for a while in Craft projects. That being said, LiquidJS looks more fully-featured than the version of Liquid I used back in the days with Jekyll ... but I digress.

Back to my rule of thumb: when modularizing code, use all the tools offered by templating languages first. Only reach for custom filters and shortcodes when your use case requires it.

Layouts

Among other things, I am quite fond of Nunjucks' template inheritance concept. The combination of extends and block allows authors to chain multiple templates and to define blocks that extending templates can override or not. Nunjucks templates share the same scope or context, which means defined variables are available to other templates in that chain and can also be overridden.

As a rule of thumb, I use Nunjucks template inheritance for layouts and only use Eleventy's layout system when I need to specify a layout in a markdown file front matter. In that case, the called Nunjucks template has a {{ content | safe }} tag where I want the content of my Markdown file to appear and Nunjucks takes over from then on.

Filters

Most templating languages offer a bunch of built-in filters. When they are not quite up to snuff, Eleventy allows you to create custom filters using all the power of JavaScript and Node, as well as the ecosystem of packages, modules and libraries coming along with it.

Nunjucks has no filter to format dates? We can harness the power of Luxon and create one. How about localisation while we're at it?

/**
 * Format a date with Luxon
 *
 * @param {String} date - string Date
 * @param {String} format - date format (Luxon)
 * @param {String} locale - locale
 * @returns {String} formatted date
 */

const { DateTime } = require("luxon");

module.exports = function (date, format, locale = "en") {
  date = new Date(date);
  return DateTime.fromJSDate(date).setLocale(locale).toFormat(format);
};

We make our filter available in Nunjucks, Liquid, Handlebars and JavaScript by adding it to .eleventy.js. Luxon is included in Eleventy but let's add it to our package.json for good measure: npm i -D luxon.

module.exports = function (eleventyConfig) {
  // ... more config ...
  eleventyConfig.addFilter(
    "formatDate",
    require("./src/_11ty/filters/formatDate.js")
  );
  // ... more config ...
};

Usage:

{{ "2021-08-06" | formatDate("DDD") }}
<time datetime="{{ post.date | formatDate('yyyy-MM-dd') }}">{{ post.date | formatDate("DDD", "fr") }}</time>

Another type of filters I see myself creating regularly are the ones allowing me to filter collections. Let's say we need to display only posts belonging to certain categories in our templates.

/**
 * Filter collection by categories
 *
 * @param {Array} collection - collection (assuming front-matter have a 'categories' key)
 * @param {Array} categories - array of categories (if string supplied, turn into array)
 * @returns {Array} collection items from specified categories
 */

module.exports = function (collection, categories) {
  let results = new Set();

  if (typeof categories === "string") {
    categories = Array.of(categories);
  }

  categories.forEach((cat) => {
    let matches = collection.filter((item) =>
      item.data["categories"].includes(cat)
    );
    matches.forEach((item) => results.add(item));
  });

  results = Array.from(results).sort((a, b) => a.date - b.date);

  return results;
};

Let's add the filter to our Eleventy configuration.

module.exports = function (eleventyConfig) {
  // ... more config ...
  eleventyConfig.addFilter(
    "getByCategories",
    require("./src/_11ty/filters/getByCategories.js")
  );
  // ... more config ...
};

We can then use it like this in our templates:

{% set yummyPosts = collections.posts | getByCategories(["meals", "desserts"]) %}

Includes

Nunjucks includes do not have a separate scope and do not take parameters. However, they can be nested and have access to variables defined in the template context.

My use cases for includes are static partials or the ones only needing access to variables available in the Nunjucks template context: header, footer, html <head>, navigation, pagination, etc.

Here is an include for a navigation interface that is itself included in a header.

{##
 # - get nav items from data file (./src/_data/mainnav.js)
 # - activeSection is set by Nunjucks and available in the template context
 # - if activeSection is equal to item.navTrigger, display active class and aria-current
 # - display navUrl, navLabel for each item
#}
<nav aria-label="main navigation">
  {% for item in mainnav %}

    {% set activeClass = "" %}
    {% set activeAria = "" %}
    {% if item.navTrigger == activeSection %}
      {% set activeClass = "is-active" %}
      {% set activeAria = 'aria-current="page"' | safe %}
    {% endif %}

    {% if loop.first %}<ul class="c-mainnav">{% endif %}
      <li class="c-mainnav__item">
        <a class="c-mainnav__link  {{ activeClass }}" href="{{ item.navUrl }}" {{ activeAria }}>{{ item.navLabel }}</a>
      </li>
    {% if loop.last %}</ul>{% endif %}

  {% endfor %}
</nav>

Nunjucks macros

Macros are a bit more powerful and a bit more involved than includes. They have their own scope by default and can be passed positional or named parameters. They must also be imported using {% from %} or {% import %} before being used.

I use macros as soon as I need components with parameters and a small amount of logic. Their main advantage is their legibility when you need to output a non-trivial amount of HTML.

{% macro itemPost(title, date, url, featured, locale="en") -%}

  {% set featuredClass = "c-blogteaser--featured" if featured %}

  <article class="c-blogteaser {{ featuredClass }}">
    <p class="c-blogteaser__date"><time datetime="{{ date | formatDate('yyyy-MM-dd') }}">{{ date | formatDate("DDD", locale) }}</time></p>
    <h2 class="c-blogteaser__title"><a class="c-blogteaser__link" href="{{ url }}">{{ title }}</a></h2>
  </article>

{% endmacro %}

Now we can import it and use it.

{% from "macros/itemPost.njk" import itemPost %}

{% set posts = collections.posts %}
{% for item in posts %}
  {% if loop.first %}<ul>{% endif %}
    <li>
      {{ itemPost(
        title = item.data.title,
        date = item.date,
        url = item.url,
        featured = item.data.featured
      ) }}
    </li>
  {% if loop.last %}</ul>{% endif %}
{% else %}
  <p>No post found</p>
{% endfor %}

A minor drawback of Nunjucks macros is that they need to be explicitly imported. In that regard, the LiquidJS render tag appears to be a bit more flexible. Then again, we are explicitly importing components in "React and friends" all day long.

Eleventy shortcodes

Eleventy shortcodes are essentially a way to create custom tags in various template languages, which makes them the most powerful option at our disposal to create components.

They can pretty much do everything Nunjucks macros can do and then some.

I reach for shortcodes when I need advanced logic, fine grained control over errors, NPM modules or async components fetching data or reading files. Paired shortcodes also help when there is a big block of content to process.

Like many, I will often reach for shortcodes to provide content authors with the ability to include snippets of HTML into Markdown files: styled Youtube embeds or figures with captions are common use cases.

Eleventy being its usual flexible self, most shortcodes can be made universal, which makes them available in all template languages that supports them (Nunjucks, Liquid, JavaScript, Handlebars).

In order to use them in Markdown files (you can use includes or macros that way too), set markdownTemplateEngine in your .eleventy.js config file to njk. That tells Eleventy to process markdown files with Nunjucks before rendering them to HTML.

Speaking of Nunjucks, here is a shortcode that will render the content of any markdown file in a template.

/**
 * Returns rendered markdown from a file
 *
 * @param {String} path - Path of the file to render
 */

const fs = require("fs");
const path = require("path");
const md = require("markdown-it");

module.exports = function (filePath) {
  filePath = path.resolve(filePath);

  if (path.extname(filePath) !== ".md") {
    throw new Error(`RenderMdFile expects Markdown files.`);
  }

  const fileContent = fs.readFileSync(filePath).toString();
  return md.render(fileContent);
};

Again, we have to declare the shortcode in our Eleventy configuration (you know the drill by now), before we can use it in our Nunjucks templates.

{% renderMdFile "src/content/markdown/test.md" %}

Famous last words

I am personally really fond of the HTML first approach taken by Nunjucks and Eleventy for server-side rendered components.

However, it seems (server-side rendered first) JavaScript components are banging hard on the door of the SSG world lately. Projects like eleventy-plugin-vue, Slinkity and Astro are all moving in this direction.

I have a feeling we might soon all write all-encompassing server-side rendered first, hydrated on demand components handling data, markup, styling and interactions.

Coupled with my lack of personal conventions regarding projects architecture, the unopinionated nature of Eleventy meant that all my projects were organized slightly differently. As a result, I lost some time figuring out how things were configured and organized when jumping from one project to another. Reusing code from project to project was also made more difficult.

In short, it was time for a minimal amount of structure and conventions. Here is what I came up with:

Files and folders

+-- build_tasks/
+-- src/
  +-- _11ty/
    +-- collections/
    +-- filters/
    +-- shortcodes/
    +-- utils/
  +-- _data/
  +-- _includes/
    +-- layouts/
    +-- macros/
    +-- partials/
    +-- svg/
  +-- assets/
    +-- fonts/
    +-- img/
    +-- js/
    +-- scss/
  +-- content/
    +-- en/
    +-- fr/
+-- .eleventy.js
+-- .gitignore
+-- package-lock.json
+-- package.json
+-- README.md

• build_tasks: I generally use NPM scripts as my asset pipeline. Occasionally, I need something more than an NPM package and a one liner. Those slightly more involved build scripts live in this directory.
• src/_11ty: contains everything required by the .eleventy.js config file: collections, filters, shortcodes and utilities all go in their own directories. Reusing these in another project amounts to copying a file, installing dependencies if needed and requiring the file in .eleventy.js.
• src/_data: data directory containing static or dynamic local data files. Pretty much standard in Eleventy projects.
• src/_includes: I use Nunjucks extensively, along with template inheritance and extends, which means layouts, includes and macros must live in this directory.
• src/_includes/layouts: layouts used by the project. I use Nunjucks template inheritance whenever possible. Blocks makes it a superior layout system for me compared to the (simpler) Eleventy layout system.
• src/_includes/partials: components that do not require any parameters other than those available in the global template context. Used for things like header, footer, etc.
• src/_includes/macros: Nunjucks macros are locally scoped and accept parameters / arguments. Used for standard components (cards, etc) and utilities (format dates, etc.).
• src/_includes/svg: SVG code to be included inline in pages. SVG are optimized and accessible.
• src/assets: static and processed assets. Typically contains scss, img, fonts and js directories. Most of these are handled by a build process, while others, like fonts are copied by 11ty.
• src/content: the content of the site, be it Nunjucks or Markdown files. I generally use directories and getFilteredByGlob(Glob) to define collections, rather than using tags. For multilingual projects, I create subdirectories containing directory data files to define locales as direct children of the content directory.

Head over to Youtube if you'd rather see a video where I go through this while frantically moving my mouse cursor around.

I am sure these conventions I have set for myself will still evolve (escaping entropy is an illusion) but, so far, this way of loosely structuring projects makes sense to me and allows me to be more productive.

Objectives

The website I was working on could potentially have up to 12 video players on a single page. For performance reasons, I didn't want to load all these iframe and their content on first load. The client also wanted their videos to have a custom cover image and was using Vimeo and Youtube as video services.

On my side, I wanted to come up with something simple to maintain and that didn't depend on the ever-changing APIs of these services. I also wanted a fallback in the form of a link to these video services if the JavaScript didn't work or was not loaded.

Since I was going for a progressively enhanced solution, I settled on JavaScript modules as my cut the mustard test and checked for template tag support on top of that.

HTML foundations

I started with some (hopefully) semantic HTML code:

• a working link to the video on the relevant service
• a responsive cover image
• data attributes to store the ID of the video and the video service (used to dynamically create the iframe relevant src value with JavaScript)

<div class="c-videoplayer  js-video-player" data-video-service="vimeo" data-video-id="174919644">
  <a class="c-videoplayer__link  js-video-link" href="https://vimeo.com/174919644" aria-label="play video: video title">
    <img src="https://picsum.photos/id/239/600/338"
         srcset="https://picsum.photos/id/239/600/338 600w,
                 https://picsum.photos/id/239/800/450 800w"
         sizes="(min-width: 1440px) 720px,
               (min-width: 750px) 50vw,
               100vw"
         class="c-videoplayer__cover"
         loading="lazy"
         decoding="async"
         alt="">
  </a>
  <template class="js-video-template">
    <iframe src="" allow="autoplay; fullscreen" allowfullscreen></iframe>
  </template>
</div>

I decided to have a template tag wrapped around the iframe to prevent it from rendering on page load. While it is certainly possible to generate the iframe entirely in JavaScript, it made more sense to me to have as much of the markup as possible in the HTML.

I also included that template inside every video player to make it more of a self-contained "component".

Add some CSS

In terms of styles, the player needed to always have an aspect ratio of 16 by 9. The link or the iframe could then be absolutely positioned relative to the player to fill all the available space. A custom SVG "play" icon can be thrown in using generated content.

/* --------------------------------
videoplayer
-------------------------------- */

.c-videoplayer {
  position: relative;
  background-color: black;
  aspect-ratio: 16 / 9;
  background: #000000;
}

@supports not (aspect-ratio: 16 / 9) {
  .c-videoplayer {
    padding-top: 56.25%;
  }
}

.c-videoplayer__link,
.c-videoplayer > iframe {
  border: none;
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
}

.c-videoplayer__link::after {
  content: "";
  position: absolute;
  top: 50%;
  left: 50%;
  width: 60px;
  height: 60px;
  transform: translate3d(-50%, -50%, 0);
  background-image: url(../img/icon_play.svg);
  background-position: 50% 50%;
  background-repeat: no-repeat;
  background-size: cover;

  transition: transform 0.2s ease-out;
}

@media all and (min-width: 500px) {
  .c-videoplayer__link::after {
    width: 72px;
    height: 72px;
  }
}

.c-videoplayer__link:hover::after,
.c-videoplayer__link:focus::after {
  transform: translate3d(-50%, -50%, 0) scale(1.1);
}

.c-videoplayer__cover {
  display: block;
  width: 100%;
  height: 100%;
  object-fit: cover;
  transition: opacity 0.2s ease-out;
}

.c-videoplayer__link:hover > .c-videoplayer__cover,
.c-videoplayer__link:focus > .c-videoplayer__cover {
  opacity: 0.72;
}

We now have a working baseline in the form of an humble anchor tag wrapped around a responsive cover image and linking to the video on the relevant video service.

We can now add a layer of JavaScript to replace that link with a fully functional iframe when the link is clicked.

A sprinkle of JS

If we break down what our JavaScript code needs to accomplish, here is what we come up with:

• test if the browser supports the template element (and bail out if it does not)
• use the values of the data-video-service and data-video-id attributes to create the relevant src value for the iframe
• grab the template and import its content
• generate and add the relevant src value to the iframe
• replace the link with a functional iframe when the link is clicked

/**
 * CSS selectors
 */
const SELECTORS = {
  player: ".js-video-player",
  link: ".js-video-link",
  template: ".js-video-template",
};

/**
 * Check if HTML templates are supprted
 * @returns {Boolean} is template tag supported
 */
function supportsTemplate() {
  return "content" in document.createElement("template");
}

/**
 * Build iframe src value
 * @param {String} videoService
 * @param {String} videoId
 * @returns {String} src url for iframe
 */
function getIframeSrc(videoService, videoId) {
  let iframeSrc = "";
  if (videoService === "youtube") {
    iframeSrc = `https://www.youtube.com/embed/${videoId}?autoplay=1`;
  }
  if (videoService === "vimeo") {
    iframeSrc = `https://player.vimeo.com/video/${videoId}?color=e76c34&title=0&byline=0&portrait=0&autoplay=1`;
  }
  return iframeSrc;
}

/**
 * Get all players in the page
 * Swap the placeholder image and link for a video iframe
 */
function init() {
  // cut the mustard test
  if (!supportsTemplate()) {
    console.log("Your browser does not support the template tag");
    return;
  }

  // get all players
  const players = document.querySelectorAll(SELECTORS.player);

  // loop through players
  players.forEach((player) => {
    // get values
    const service = player.dataset.videoService;
    const id = player.dataset.videoId;

    // checks
    if (service !== "youtube" && service !== "vimeo") return;
    if (!id) return;

    // prepare iframe src and check
    const iframeSrc = getIframeSrc(service, id);
    if (iframeSrc === "") return;

    // get and import template
    const template = player.querySelector(SELECTORS.template);
    const templateContent = document.importNode(template.content, true);

    // get iframe
    const iframe = templateContent.querySelector("iframe");

    // add src to iframe
    iframe.src = iframeSrc;

    // get link
    const link = player.querySelector(SELECTORS.link);

    // when link is clicked,
    // replace link (and image) with the template content
    link.addEventListener(
      "click",
      function (event) {
        event.preventDefault();
        link.replaceWith(templateContent);
      },
      false
    );
  });
}

export default init;

On the CMS or SSG side of things, we need the following pieces of data:

• a string to identify the service used to host the video
• the ID of the video
• the title of the video
• a full URL to the video on Youtube or Vimeo (can be built from the ID and service)

We now have a minimalist customizable and maintainable video player falling back to a link wrapped around a responsive image. We can also have a page with many of those players without loading several iframe and their content when that page is initially loaded.

The main downside of using this method is that, using mobile browsers, videos will not autoplay, which means users will need to make two clicks to play them. To me, that's a very reasonable tradeoff to make.

Then and now

With Craft 2, my go-to approach to build modular element queries was to manipulate objects with Twig before passing them to element queries as parameters. Here is a basic example using categories and relations in Craft 2.

{# get category ID from URL parameter #}
{% set selectedCatId = craft.request.getParam('category') ?? null %}

{# initial query parameters #}
{% set queryParams = {
  section: 'blog',
  order: 'postDate desc',
  limit: 10
} %}

{# add relatedTo if needed #}
{% if selectedCatId %}
  {% set queryParams = queryParams|merge({
    relatedTo: selectedCatId
  }) %}
{% endif %}

{# execute query #}
{% set blogposts = craft.entries(queryParams).find() %}

Since version 3, Craft favors the use of dot syntax and chained functions, which means we have to change our approach slightly. However, we can essentially accomplish the same thing using Twig's {% do %} tag.

The Twig documentation is quite succinct and could probably be fleshed but a little bit. Essentially, do executes whatever is passed to it but does not print or return any value, which is exactly what we need.

{# get category ID from URL parameter #}
{% set selectedCatId = craft.app.request.getParam("category") ?? null %}

{# initial query #}
{% set query = craft.entries()
  .section("blog")
  .orderBy("postDate desc")
  .limit(10) %}

{# add relatedTo if needed #}
{% if selectedCatId %}
  {% do query.relatedTo(selectedCatId) %}
{% endif %}

{# execute query #}
{% set blogposts = query.all() %}

Cumulative filters and search

Here is a slightly more advanced example involving categories, publication years and search.

We want a paginated list of blogposts and the ability to filter them by publication year, by categories and also be able to search on titles. The search and filters should be cumulative. For example, we want to be able to search all blogposts published in 2016, belonging to the "Gardening" category and that have "Brad" in their title.

Here is the plan:

1. create a form using post or get to set parameters and values (use get if you want the parameters and values to be visible in the URL)
2. retrieve values using craft.app.request.getParam()
3. create a base query
4. add parameters to base query as needed using retrieved values

{# -------------------------------------------------
layout
------------------------------------------------- #}

{% extends "_layouts/base.twig" %}


{# -------------------------------------------------
variables
------------------------------------------------- #}

{# get parameters from request and set default values #}
{% set searchTerm = craft.app.request.getParam("search") ?? null %}
{% set selectedCatId = craft.app.request.getParam("category") ?? null %}
{% set selectedYear = craft.app.request.getParam("year") ?? null %}

{# All blogposts query #}
{% set allBlogpostsQuery = craft.entries()
  .section("blogposts")
  .orderBy("postDate desc")
  .limit(null) %}

{# all blogposts #}
{% set allBlogposts = allBlogpostsQuery.all() %}

{# total blogposts #}
{% set totalBlogposts = allBlogpostsQuery.count() %}

{# get all categories #}
{% set allBlogCategories = craft.categories()
  .group("blogCategories")
  .orderBy("title")
  .relatedTo(allBlogposts)
  .all() %}

{# Years with blogposts published #}
{% set years = allBlogposts|group("postDate|date('Y')")|keys %}

{# override limit for pagination #}
{% set filteredBlogposts = allBlogpostsQuery.limit(2) %}

{# add before/after params if needed #}
{% if selectedYear %}
  {% do filteredBlogposts.after(selectedYear).before(selectedYear + 1) %}
{% endif %}

{# add relatedTo param if needed #}
{% if selectedCatId %}
  {% do filteredBlogposts.relatedTo(selectedCatId) %}
{% endif %}

{# add search param if needed #}
{% if searchTerm %}
  {% do filteredBlogposts.search('title:' ~ searchTerm) %}
{% endif %}

{# count results of modular query #}
{% set results = filteredBlogposts.count() %}


{# -------------------------------------------------
template
------------------------------------------------- #}

{% block content %}
  {# search form #}
  <form action="{{ url(craft.app.request.pathInfo) }}" method="post">
    <h2>Search blogposts</h2>

    {# years #}
    {% if years|length %}
      <div>
        <label for="years">Year: </label>
        {# output years #}
        {% for year in years %}
          {% if loop.first %}<select name="year" id="years">{% endif %}

            {% if loop.first %}<option value="">All</option>{% endif %}
            {% set selected = (selectedYear == year) ? "selected" : "" %}
            <option value="{{ year }}" {{ selected }}>{{ year }}</option>

          {% if loop.last %}</select>{% endif %}
        {% endfor %}
      </div>
    {% endif %}

    {# categories #}
    {% if allBlogCategories|length %}
      <div>
        <label for="cat">Category: </label>
        {# output categories #}
        {% for category in allBlogCategories %}
          {% if loop.first %}<select name="category" id="cat">{% endif %}

            {% if loop.first %}<option value="">All</option>{% endif %}
            {% set selected = (selectedCatId == category.id) ? "selected" : "" %}
            <option value="{{ category.id }}" {{ selected }}>{{ category.title }}</option>

          {% if loop.last %}</select>{% endif %}
        {% endfor %}
      </div>
    {% endif %}

    {# search #}
    <div>
      {% set searchValue = searchTerm ?? "" %}
      <label for="q">Search: </label>
      <input type="search" id="q" name="search" value="{{ searchValue }}">
    </div>
    <div>
      <input type="submit" value="Search entries">
    </div>

  </form>

  {# display results / total #}
  <h2>Results</h2>
  <p>{{ results }} result{% if results > 1 %}s{% endif %} found in {{ totalBlogposts }} blogposts.</p>

  {# paginate filtered entries #}
  {% paginate filteredBlogposts as pagination, entries %}
  {% for entry in entries %}
    {% if loop.first %}<ul>{% endif %}

    <li>
      <article>
        <p><time datetime="{{ entry.postDate|date('Y-m-d') }}">{{ entry.postDate|date('F d, Y') }}</time></p>
        <h3><a href="{{ entry.url }}">{{ entry.title }}</a></h3>
        <p>{{ entry.commonSummary }}</p>
      </article>
    </li>

    {% if loop.last %}</ul>{% endif %}
  {% endfor %}

  {# pagination #}
  {% if pagination.totalPages > 1 %}
    {% if pagination.prevUrl %}
      <a href="{{ pagination.prevUrl }}">Previous Page</a>
    {% endif %}
    {% if pagination.nextUrl %}
      <a href="{{ pagination.nextUrl }}">Next Page</a>
    {% endif %}
  {% endif %}

{% endblock %}

Mainly a shift in syntax

In most cases, modular element queries can be created using {% do %} and dot syntax instead of manipulating objects with Twig before feeding them to element queries as parameters. I would even argue that the code is a bit more legible.

The most important thing for me is that, combined with Twig as a templating language, Craft remains a very flexible and, dare I say it, elegant tool to retrieve and display data as well as to structure it.

Why Github Actions?

Services like Buddy or DeployHQ are really powerful. They allow you to setup complex build and deployment pipelines like atomic deployments using a nice GUI interface.

That being said, that power and ease of use come with a price tag which, in my opinion, can become quite high for basic projects. Most of the small to medium websites I work on do not necessarily need that level of power and complexity.

Since I generally use Github to host my repositories, being able to setup a basic deployment pipeline with a single YAML file for free seemed like an alternative worth investigating.

Deployment steps

My goal was to use Github Actions to create a basic build and deployment pipeline for Craft CMS websites. Here are the steps I needed:

1. Pull repository in container
2. Load SSH key (used by rsync)
3. Use specific version of Node
4. Install PHP dependencies with composer
5. Install Node dependencies
6. Build assets using NPM scripts
7. Deploy everything to the production server with rsync
8. Log into the production server and execute Craft commands

Security

Since this workflow needs to connect to servers using SSH, we have to create three Github Secrets in the repository we want to deploy:

• SSH_HOST: the IP address of the server we need to connect to
• SSH_USER: the SSH user
• SSH_KEY: the SSH key. The recommended option here is to create a dedicated key pair for the repository rather than using your personal key. The public key will be stored on the server, while the private key will be stored in the Github Secret.

We will now be able to reference those secrets in our workflow using the following syntax: ${{ secrets.MYSECRET }}

The end result

After reading a couple of helpful articles and blogposts, here is the craftdeploy.yaml file I came up with.

name: Craft CMS deployments

on:
  push:
    branches: [master]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
      # Pull repository into the current pipeline
      - name: Pull repository
        uses: actions/checkout@v2

      # Setup container with private SSH Key (used by rsync)
      - name: Load private SSH key
        uses: webfactory/ssh-agent@v0.4.1
        with:
          ssh-private-key: ${{ secrets.SSH_KEY }}

      # Use a specific version of Node
      - name: Setup Node
        uses: actions/setup-node@v1
        with:
          node-version: "12.x"

      # Install PHP dependencies
      - name: Composer install
        run: composer install --no-interaction --no-progress --no-suggest --optimize-autoloader

      # Install NPM dependencies
      - name: NPM install
        run: npm ci

      # Build assets using NPM scripts
      - name: Build assets
        run: npm run build

      # RSYNC
      # - rsync [options] ~/localdir ssh_user@ssh_host:destination_directory
      # - exclude web/uploads is there to avoid deleting user uploaded files w/ --delete-after
      # - StrictHostKeyChecking=no will automatically add new host keys to the user known hosts files.
      - name: Deploy with rsync
        run: |
          rsync -azh --delete-after --exclude={"/web/uploads/","/node_modules/","/.git/","/.github/"} -e "ssh -o StrictHostKeyChecking=no" ./ ${{ secrets.SSH_USER }}@${{ secrets.SSH_HOST }}:~/

      # execute Craft commands on remote server
      - name: Execute SSH commmands on remote server
        uses: appleboy/ssh-action@master
        with:
          host: ${{ secrets.SSH_HOST }}
          username: ${{ secrets.SSH_USER }}
          key: ${{ secrets.SSH_KEY }}
          script: |
            chmod a+x craft
            php craft backup/db
            php craft migrate/all
            php craft project-config/apply
            php craft clear-caches/all

By creating a craftdeploy.yaml file in ./.github/workflows/ and by setting the push event to the master branch, we ensure that this workflow will run every time we push code to the master branch of our repository.

We use rsync to deploy files from the Github container to the production server. In the script above, we are copying files from the root of our local install to the root of a remote server we connect to via SSH.

Warning: rsync is a very powerful tool and can be quite destructive if you mess up your command. If you are new to it (and event if you aren't), consult the man page to see all available options and test it using the terminal. The --dry-run option, in particular, is very useful. It will not do anything and will print out the files that would have been transferred in your terminal.

I have been testing this script with several Craft projects for a couple of months and have not experienced any issue so far. The workflow is consistently taking between 1 and 3 minutes to run, which I find rather reasonable.

Granted, this is a very basic workflow and it can certainly be improved upon. Feel free to ping me me if you have ideas.

While I will probably continue to use Buddy and the likes for more complex needs, I am also quite happy with the convenient, cheap and reliable option Github Actions provides.

Don't use await in loops

One of my older post is about fetching data from a GraphQL API with Eleventy. While the example code I wrote works, it does not retrieve data in a very performant way.

The problem is that I use await in a while loop (like a dummy). The direct consequence of this is that the API calls happen sequentially, as brilliantly explained by Jason Lengstorf. Each call has to wait for the previous one to finish instead of running in parallel.

Retrieving all records from an API at build time is a pretty common use case with static site generators and headless CMSes. Generally, such APIs are limiting the number of records you can get in one single query and will make you use pagination.

Here is a rough outline of how to deal with this use case in a performant manner:

1. Make a request to the API to retrieve a first batch of data as well as the total number of items to retrieve
2. Calculate the number of additional API requests we need to retrieve all data
3. If we need to make more calls, store those additional requests as promises
4. Use Promise.all to execute all additional requests in parallel
5. Sort our data if needed
6. Store all data in a cache file

Using promises and caching

We will use the Axios package and pagination with a limit of 1 on the JSON Placeholder API in this example. That will allow us to make 99 API calls in parallel. We will also use the flat-cache NPM package to store our data for speedier local development.

Now, on with the code! In our Eleventy install, we create a blogposts.js file in our _data folder.

// required packages
const path = require("path");
const axios = require("axios");
const flatCache = require("flat-cache");

// Config
const ITEMS_PER_REQUEST = 20;
const CACHE_KEY = "blogposts";
const CACHE_FOLDER = path.resolve("./.cache");
const CACHE_FILE = "blogposts.json";

/**
 * Request blogposts
 * @param {Int} skipRecords - number or records to skip
 * @return {Object} - Total number of items and API data
 */
async function requestPosts(skipRecords = 0) {
  try {
    const url = `https://jsonplaceholder.typicode.com/posts?_start=${skipRecords}&_limit=${ITEMS_PER_REQUEST}`;
    const response = await axios(url, {
      method: "get",
      headers: { "Accept-Encoding": "gzip,deflate,compress" },
    });

    // return the total number of items to fetch and the data
    return {
      total: parseInt(response.headers["x-total-count"], 10),
      data: response.data,
    };
  } catch (err) {
    throw new Error(err);
  }
}

/**
 * Get all posts
 * - check if we have a cache
 * - if not make api requests and create cache
 * @return {Array} - array of API data (from cache if there is one or from API)
 */
async function getAllPosts() {
  // load cache
  const cache = flatCache.load(CACHE_FILE, CACHE_FOLDER);
  const cachedItems = cache.getKey(CACHE_KEY);

  // if we have a cache, return cached data
  if (cachedItems) {
    console.log("Blogposts from cache");
    return cachedItems;
  }

  // if we do not, make queries
  console.log("Blogposts from API");

  // variables
  const requests = [];
  const apiData = [];
  let additionalRequests = 0;

  // make first request and marge results with array
  const request = await requestPosts();
  apiData.push(...request.data);

  // calculate how many additional requests we need
  additionalRequests = Math.ceil(request.total / ITEMS_PER_REQUEST) - 1;

  // create additional requests
  for (let i = 1; i <= additionalRequests; i++) {
    const start = i * ITEMS_PER_REQUEST;
    const request = requestPosts(start);
    requests.push(request);
  }

  // resolve all additional requests in parallel
  const allResponses = await Promise.all(requests);
  allResponses.forEach((response) => {
    apiData.push(...response.data);
  });

  // sort data as needed
  apiData.sort((a, b) => {
    return a.id - b.id;
  });

  // set and save cache
  if (apiData.length) {
    cache.setKey(CACHE_KEY, apiData);
    cache.save();
  }

  // return data
  return apiData;
}

// export for 11ty
module.exports = getAllPosts();

Data from our API is now available in our templates under the blogposts key. We can create our list of blogposts and, using pagination with a size of 1, we can also create all our blogposts detail pages.

By having requests running in parallel, we fetch our data in a performant manner. When comparing this approach to the sequential one used in my previous blogpost with the same API, performance is eight to ten times faster.

Storing that data in a static cache allows us to not constantly hit the API during development. I usually delete that cache as part of my build process. That way, I am sure that to get fresh data from the API or from the headless CMS every time the site is built.

If you need your caching to be more versatile and configurable, check out the eleventy-cache-assets plugin by Zach himself.

Native approach using tags

The tag system Eleventy comes with allows you to group content items into collections automatically by specifying a tags key in those content items' front matters. For example, a post about milkshakes tagged as "foods" and "drinks" will appear in both collections.foods and collections.drinks.

You can then use pagination with a size of 1 to automatically generate tag pages that will list all content items belonging to that tag's collection. Paginating the posts listed on those tag pages is another story, but we'll get to that.

Using custom categories

I generally don't use tags to create my collections. I prefer to use folders and the getFilteredByGlob( glob ) API method to do so, but I often need basic custom taxonomies to categorize my content.

Eleventy being the flexible tool that it is, creating basic custom taxonomies is relatively straightforward.

Here is what we would need to create a custom "categories" taxonomy for our blogposts:

1. a categories key and an array of values in the front matters of each of our blogposts.
2. an array of all unique categories values used in each blogpost front matter.
3. a way to filter all blogposts with a specific value in their front matters under the categories key.

Add keys and values to front matter

We'll start by adding a categories key to all blogposts and by specifying an array of categories for each of them.

---
title: "This is an amazing travel blogpost with categories"
excerpt: "This blogpost is truly amazing and is listed under different categories, read on if you feel so inclined."
categories:
- awesomeness
- travel
---

Automatically create a collection of unique categories

The easiest route here is to use the collections API in .eleventy.js. As a first step, we'll create a collection of all our blogposts.

module.exports = function (eleventyConfig) {
  // blogposts collection
  eleventyConfig.addCollection("blogposts", function (collection) {
    return collection.getFilteredByGlob("./src/blogposts/*.md").reverse();
  });
};

Once we have done that, we need a collection of all categories used in all of our blogposts, so we can use it to generate our categories archive pages. Here are the steps we will follow:

1. Loop over every item in our blogposts collection, collect all arrays of categories and flatten them in one big array.
2. Remove capitalisation.
3. Remove duplicates.
4. Sort categories alphabetically.
5. Create a slug for each category using the slugify package.

We will use lodash to flatten the nested array and for some other tasks, so we need to install and import that as well.

const lodash = require("lodash");
const slugify = require("slugify");

/**
 * Get all unique key values from a collection
 *
 * @param {Array} collectionArray - collection to loop through
 * @param {String} key - key to get values from
 */
function getAllKeyValues(collectionArray, key) {
  // get all values from collection
  let allValues = collectionArray.map((item) => {
    let values = item.data[key] ? item.data[key] : [];
    return values;
  });

  // flatten values array
  allValues = lodash.flattenDeep(allValues);
  // to lowercase
  allValues = allValues.map((item) => item.toLowerCase());
  // remove duplicates
  allValues = [...new Set(allValues)];
  // order alphabetically
  allValues = allValues.sort(function (a, b) {
    return a.localeCompare(b, "en", { sensitivity: "base" });
  });
  // return
  return allValues;
}

/**
 * Transform a string into a slug
 * Uses slugify package
 *
 * @param {String} str - string to slugify
 */
function strToSlug(str) {
  const options = {
    replacement: "-",
    remove: /[&,+()$~%.'":*?<>{}]/g,
    lower: true,
  };

  return slugify(str, options);
}

module.exports = function (eleventyConfig) {
  // create blog collection
  eleventyConfig.addCollection("blogposts", function (collection) {
    return collection.getFilteredByGlob("./src/blogposts/*.md").reverse();
  });

  // create blog categories collection
  eleventyConfig.addCollection("blogCategories", function (collection) {
    let allCategories = getAllKeyValues(
      collection.getFilteredByGlob("./src/blogposts/*.md"),
      "categories"
    );

    let blogCategories = allCategories.map((category) => ({
      title: category,
      slug: strToSlug(category),
    }));

    return blogCategories;
  });

  // filters
  eleventyConfig.addFilter("date", require("./filters/dateformat.js"));
  eleventyConfig.addFilter("include", require("./filters/include.js"));

  // return modified config
  return {
    dir: {
      input: "./src",
      output: "./dist",
    },
  };
};

Filter blogposts by categories

We can now create our categories pages by paginating the blogCategories collection. In that template, we will use a custom includes filter to get only the blogposts containing the category we are interested in from the blogposts collection. That filter compares values without taking accentuated characters or capitalization into account. It also uses lodash.

const lodash = require("lodash");

/**
 * Select all objects in an array
 * where the path includes the value to match
 * capitalisation and diacritics are removed from compared values
 *
 * @param {Array} arr - array of objects to inspect
 * @param {String} path - path to inspect for each object
 * @param {String} value - value to match
 * @return {Array} - new array
 */

module.exports = function (arr, path, value) {
  value = lodash.deburr(value).toLowerCase();
  return arr.filter((item) => {
    let pathValue = lodash.get(item, path);
    pathValue = lodash.deburr(pathValue).toLowerCase();
    return pathValue.includes(value);
  });
};

And here is a bare-bones template using pagination with a size of 1 and that includes filter to create our categories pages.

---
pagination:
  data: collections.blogCategories
  size: 1
  alias: category
permalink: /blog/category/{{ category.slug }}/index.html
---
{% extends "layouts/base.njk" %}

{% block content %}

  <h2>Blog category: {{ category.title }}</h2>
  {% set posts = collections.blogposts | include("data.categories", category.title) %}
  {% for post in posts %}
    {% if loop.first %}<ul>{% endif %}
      <li>
        <article>
          <p><time datetime="{{ post.date | date('YYYY-MM-DD') }}">{{ post.date | date("MMMM Do, YYYY") }}</time></p>
          <h2><a href="{{ post.url }}">{{ post.data.title }}</a></h2>
        </article>
      </li>
    {% if loop.last %}</ul>{% endif %}
  {% endfor %}

  <h3>Categories</h3>
  {% for category in collections.blogCategories %}
    {% if loop.first %}<ul><li><a href="/blog/">All</a></li>{% endif %}

    <li>
      <a href="/blog/category/{{ category.slug }}">{{ category.title }}</a>
    </li>

    {% if loop.last %}</ul>{% endif %}
  {% endfor %}

{% endblock %}

As a first step, we replicated the native tag-based functionality using our own custom category system.

Since we already used pagination to create our categories pages, we cannot use it in the same template to paginate our posts. That being said, Zach Leatherman's answer to this issue on Github points to a way to format our data to get around that current limitation of Eleventy.

Two levels of pagination

In order to use Zach's solution, we need to massage our data into a collection where each item is a page of the paginated results we want for each theme. We can then use pagination with a size of 1 to create category pages with paginated posts.

If we have three blogposts in the "travel" category and one in the "awesomeness" category and we want two posts per page, we will need data in the following format:

[
  {
    title: 'travel',
    slug: 'travel',
    pageNumber: 0,
    totalPages: 2,
    pageSlugs: {
      all: [],
      next: 'travel/2',
      previous: null,
      first: 'travel',
      last: 'travel/2'
    },
    items: [{},{}]
  },
  {
    title: 'travel',
    slug: 'travel/2',
    pageNumber: 1,
    totalPages: 2,
    pageSlugs: {
      all: [],
      next: null,
      previous: 'travel',
      first: 'travel',
      last: 'travel/2'
    },
    items: [{}]
  },
  {
    title: 'awesomeness',
    slug: 'awesomeness',
    pageNumber: 0,
    totalPages: 1,
    pageSlugs: {
      all: [],
      next: null,
      previous: null,
      first: 'awesomeness',
      last: 'awesomeness'
    },
    items: [{}]
  }
]

Using some array manipulation, we can create such a collection in our .eleventy.js file.

// create flattened paginated blogposts per categories collection
// based on Zach Leatherman's solution - https://github.com/11ty/eleventy/issues/332
eleventyConfig.addCollection("blogpostsByCategories", function (collection) {
  const itemsPerPage = 2;
  let blogpostsByCategories = [];
  let allBlogposts = collection
    .getFilteredByGlob("./src/blogposts/*.md")
    .reverse();
  let blogpostsCategories = getAllKeyValues(allBlogposts, "categories");

  // walk over each unique category
  blogpostsCategories.forEach((category) => {
    let sanitizedCategory = lodash.deburr(category).toLowerCase();
    // create array of posts in that category
    let postsInCategory = allBlogposts.filter((post) => {
      let postCategories = post.data.categories ? post.data.categories : [];
      let sanitizedPostCategories = postCategories.map((item) =>
        lodash.deburr(item).toLowerCase()
      );
      return sanitizedPostCategories.includes(sanitizedCategory);
    });

    // chunck the array of posts
    let chunkedPostsInCategory = lodash.chunk(postsInCategory, itemsPerPage);

    // create array of page slugs
    let pagesSlugs = [];
    for (let i = 0; i < chunkedPostsInCategory.length; i++) {
      let categorySlug = strToSlug(category);
      let pageSlug = i > 0 ? `${categorySlug}/${i + 1}` : `${categorySlug}`;
      pagesSlugs.push(pageSlug);
    }

    // create array of objects
    chunkedPostsInCategory.forEach((posts, index) => {
      blogpostsByCategories.push({
        title: category,
        slug: pagesSlugs[index],
        pageNumber: index,
        totalPages: pagesSlugs.length,
        pageSlugs: {
          all: pagesSlugs,
          next: pagesSlugs[index + 1] || null,
          previous: pagesSlugs[index - 1] || null,
          first: pagesSlugs[0] || null,
          last: pagesSlugs[pagesSlugs.length - 1] || null,
        },
        items: posts,
      });
    });
  });

  return blogpostsByCategories;
});

Now, by using the following template with a pagination size of 1, we will get paginated blogposts for our categories pages.

---
pagination:
  data: collections.blogpostsByCategories
  size: 1
  alias: category
permalink: /blog/category/{{ category.slug }}/index.html
---
{% extends "layouts/base.njk" %}

{% block content %}

  <h2>Blog category: {{ category.title }}</h2>
  {% for post in category.items %}
    {% if loop.first %}<ul>{% endif %}
      <li>
        <article>
          <p><time datetime="{{ post.date | date('YYYY-MM-DD') }}">{{ post.date | date("MMMM Do, YYYY") }}</time></p>
          <h2><a href="{{ post.url }}">{{ post.data.title }}</a></h2>
        </article>
      </li>
    {% if loop.last %}</ul>{% endif %}
  {% endfor %}

  {% if category.totalPages > 1 %}
    <ul>
      {% if category.pageSlugs.previous %}<li><a href="/blog/category/{{ category.pageSlugs.previous }}/">Previous</a></li>{% endif %}
      {% if category.pageSlugs.next %}<li><a href="/blog/category/{{ category.pageSlugs.next }}/">Next</a></li>{% endif %}
    </ul>
  {% endif %}

  <h3>Categories</h3>
  {% for category in collections.blogCategories %}
    {% if loop.first %}
      <p><a href="/blog/">All</a></p>
    {% endif %}
    <p><a href="/blog/category/{{ category.slug }}">{{ category.title }}</a></p>
  {% endfor %}

{% endblock %}

My two cents on pagination

From my perspective, paginating posts on tag or category pages is a relatively common requirement, even for simple websites that have a fair amount of content, like blogs for example. In my humble opinion, pagination as it currently stands has two distinct drawbacks:

1. It can be used to generate single pages from data/collections and to paginate arrays and objects, which can make it confusing for newcomers.
2. Since it lives in the front-matter of templates, it can only be used once per template instead of being usable in context with any iterable.

If most use cases are limited to two levels of depth, then distinguishing pagination from single pages generation would probably fit the bill, since we could then combine both usages. Maybe something like a generatePages() collection method would be a good candidate.

If what’s needed is unlimited levels of depth, most other systems I have used (SSG/CMS) have something like a filter or tag that paginates any iterable in a template where needed. They return a chunked nested array of items, along with variables needed to create pagination interfaces. The closest thing I can think about in Eleventy today is the navigation plugin, but a pagination plugin is a big departure from what currently exists.

Decoupling

Both as a teacher and as a freelancer, I firmly believe that the JAMstack movement and the general trend towards decoupling the view and data layers are here to stay.

I have been teaching Craft CMS as a database-driven CMS since it was first released. Pixel & Tonic releasing a native headless mode and a solid native GraphQL API only confirmed my choice.

Jekyll, while very good at generating a site based on Markdown and static data files, requires either a plugin or a build process in front of it to consume data from APIs or headless CMSes.

Students (and myself) also have to install and maintain a Ruby environment to be able to use it. Eleventy is built on Node, which is easier to install and maintain as a development environment. It also means that students can leverage their existing knowledge of Javascript.

Extensibility

Working within a familiar environment and being able to extend and configure Eleventy using a language students already know and understand is a game changer.

Need custom filters or shortcodes? Use Javascript. Create custom order or filters for your collections before using them in your templates? Same deal. Use NPM packages to help you build the functionalities your project needs? You're already in Node.

For students, this is invaluable. Granted, Eleventy might feel a bit closer to the metal compared to Jekyll but the increased flexibility, extensibility and familiarity is definitely worth it.

Simplicity

With React, Vue or Svelte being all the rage these days, SSG like Gatsby or Gridsome were also on my radar.

Personally, I feel that those solutions, while extremely valuable when you have to deal with app-like functionalities and / or state-based UI, come with a lot of baggage and are a bit overkill when building content-driven websites.

By comparison, Eleventy is a lot simpler and looks a lot less like a black box to me (if I am being completely honest). Fetching data from a GraphQL API is quite trivial and students can still use what they learned with my colleagues teaching them Vue or Node if the project requires it.

Workshop course and sample website

All things considered, I am really happy with how the course went this year. Students seemed to enjoy it and got the hang of it pretty quickly.

My "introduction to Eleventy" course is available on Github in French and English, along with a sample website hosted on Netlify. Feel free to check both out and to give feedback, open issues or make pull requests if you think something could be improved.

As I have said in the past, teaching in the open is part of my attempt to stay relevant while teaching front-end design in this ever-moving, ever-changing messy web of ours.

Set the stage

With most static sites generators supporting a templating languages, structured data and URL control, building a multilingual website is a relatively easy task. I wrote a small blogpost on how to do it with Eleventy. Other systems like Hugo and Jekyll have either clear documentation or numerous articles on the topic.

What we want here is to redirect users that are on a certain piece of content in one language to the same one in other languages. If such a piece of content is not available, we will redirect users to the homepage of the site in the language they chose.

We will be using Eleventy (11ty) but the general approach is usable with most other SSGs. Here is what we will need:

1. A way to loop through all languages used in the site
2. Make sure each piece of content has a locale key with its value set to the language code of that content. Here is a refresher about how to do it with Eleventy directory data files if you need one.
3. Set a common unique translationKey to create a relation between the same content in various languages

Site languages

The first thing we need is an array of all the languages the site uses. I usually store that in my ./src/_data/site.js file under a languages key.

module.exports = {
  title: "Webstoemp",
  description:
    "Webstoemp is the portfolio and blog of Jérôme Coupé, a designer and front-end developer from Brussels, Belgium.",
  url: "https://www.webstoemp.com",
  baseUrl: "/",
  author: "Jerôme Coupé",
  authorTwitter: "@jeromecoupe",
  buildTime: new Date(),
  languages: [
    {
      label: "english",
      code: "en",
    },
    {
      label: "français",
      code: "fr",
    },
  ],
};

Using this array, we will be able to loop through our site languages and match the value of the code key against the value of the locale variable available in all our content files.

Setup translation keys

We now need an explicit relation between the same pieces of content in various languages. With a static site generator storing data as files, we can rely on using the same translation key in the YAML front matters of all those files. That translation key can be any string, provided that it is unique for each piece of content.

For example, we could use the following to link together our contact pages in various languages.

./src/en/pages/about.njk

---
permalink: "/{{ locale }}/about/index.html"
translationKey: "aboutPage"
---

./src/fr/pages/about.njk

---
permalink: "/{{ locale }}/a-propos/index.html"
translationKey: "aboutPage"
---

The same principle can apply to our collection items, for example blogposts.

./src/en/bogposts/2019-09-12-my-awesome-blogpost.njk

---
title: "My awesome blogpost"
translationKey: "awesome-blogpost"
---

./src/fr/bogposts/2019-09-12-mon-magnifique-blogpost.njk

---
title: "Mon magnifique blogpost"
translationKey: "awesome-blogpost"
---

We now have an explicit relation between the same content pieces in all languages.

Coding our language switcher

Here is an outline of what we are going to do with that short piece of code:

1. Loop through all languages declared for the site in ./src/_data/site.js
2. By default, set translatedUrl to the homepage of the language we are looping though. This will be overridden in step 4 if a match is found
3. Within our first loop, we will loop through all the content pieces in the site. With Eleventy, we can use the handy collections.all shortcut.
4. For each content piece we loop through, check if its translationKey matches the current item's translationKey and if its locale matches the code of the language we are looping through in our first loop. If we find a match, set translatedUrl to the url of that content item.
5. Use the value of translatedUrl to create the links in our language switcher.

{# loop though site.languages #}
{% for lgg in site.languages %}
  {% if loop.first %}<ul class="c-lggnav">{% endif %}

  {# set translatedUrl to the homepage of that language by default #}
  {% set translatedUrl = "/" + lgg.code + "/" %}

  {# set current language class #}
  {% set activeClass = "is-active" if lgg.code == locale else "" %}

  {# loop through all the content of the site #}
  {% for item in collections.all %}

    {# for each item in the loop, check if
    - its translationKey matches the current item translationKey
    - its locale matches the code of the language we are looping through #}
    {% if item.data.translationKey == translationKey and item.data.locale == lgg.code %}
      {% set translatedUrl = item.url %}
    {% endif %}

  {% endfor %}

  <li class="c-lggnav__item">
    <a class="c-lggnav__link  {{ activeClass }}" href="{{ translatedUrl }}">{{ lgg.label }}</a>
  </li>

  {% if loop.last %}</ul>{% endif %}
{% endfor %}

There we go, job done with a minimal amount of effort. Those loops will happen on every page of the site but, since Eleventy is already creating collections.all anyway and has very fast IO, the impact on build time should be pretty low, even with large sites.