Jamie Curran - Leicestershire-based Web Developer | Using Twig in Eleventy (11ty)

Education

When I first started using Eleventy, I wanted to do my templating in Twig, which is why I was delighted when I found a plugin for it. The only trouble was, being a complete noob to Eleventy and how it worked, I found the readme didn't quite have the information I was looking for in order to start using it. After tinkering around with Eleventy in the context of Nunjucks which is quite similar to Twig, I went back to it, and found I was able to work it out. As such, I decided to put together a guide so other Eleventy noobs looking to use Twig would have an easier time of it off the bat. And so I present to you:

How to use Eleventy with Twig

Getting Started

To start with, if you haven’t already, make a new folder and open it in the terminal. Then, assuming you already have NodeJS installed, run

npm init -y

Then to install Eleventy, run

npm install @11ty/eleventy

First install the plugin with

npm install --save-dev @factorial/eleventy-plugin-twig @11ty/eleventy-img twig

Next, if you haven’t already, create a file in your root directory (where your project files are) called .eleventy.config.js . This will be where you can customise how eleventy works.

Then in .eleventy.config.js, above your module.exports function create a new variable like so const eleventyPluginTwig = require("@factorial/eleventy-plugin-twig"); then inside your module.exports function, add a line that says eleventyConfig.addPlugin(eleventyPluginTwig, USER_OPTIONS);

So your .eleventy.config.js file should look like:

// .eleventy.config.js

const eleventyPluginTwig = require("@factorial/eleventy-plugin-twig");

const USER_OPTIONS = {
    dir: {
        input: "src",
        output: "dist"
    }
};

module.exports = function(eleventyConfig) {
    eleventyConfig.addPlugin(eleventyPluginTwig, USER_OPTIONS);
    return {
        dir: {
            input: "src",
            output: "dist"
        }
    }
}

Notice the presence of the USER_OPTIONS variable - by default, the plugin won’t be able to find the dir object in your eleventy config, so you can just copy and paste your dir object into the USER_OPTIONS variable.

Next, if you haven’t already, go to your package.json file and where it references “scripts”, remove the “test” script and add:

"scripts": {
	"start": "eleventy --serve" //This is eleventy's watch function and sets up a BrowserSync instance in your browser
	"build": "eleventy" //This builds all of the files you've written and outputs the raw html into your "output" folder you specified in your config file
}

If you run npm run start now, it will probably throw an error about a mixManifest file not being found, in this case you can go into node-modules/@factorial/eleventy-plugin-twig/lib/plugin.js and remove all references to mixManifest and it should work (This may not be the best way to do this, but it’s the way that worked for me!)

Once that’s done, Eleventy should run without issue.

Setting up your Twig templates

Now, if you create a _includes folder in the directory you specified as the “input” path in your eleventy config file, and create a file called base.twig , you should be able to put a basic html template in there like so

//base.twig (This file can be called anything, but we're calling it base in this case)

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Twig in Eleventy</title>
</head>
<body>
  <h1>{{ title }}</h1>
</body>
</html>

Note the {{ title }} . Next we’ll create a markdown file in the top level of the src folder and call it index.md and it should look something like this:

//index.md
---
title: My first Eleventy project in Twig
layout: base.twig
---

Now if we go to the front end of our site (you will have gotten the URL in the output of eleventy —serve), you should see a heading that reads “My first Eleventy project in Twig”!

Whatever you put under the frontmatter in a markdown file can be accessed in your twig template with

{{ content }}
//or
{{ content | raw }} //If you're passing html, content | raw will parse it and output it as HTML

And that’s it! You’ve made an Eleventy template in Twig! 🎉

For more information about Twig.js (on which this plugin is based) you can check out the github repo. For more info about twig and its syntax, you can check out the documentation.

As I work with Twig and Eleventy more, it's likely I'll be updating this post, so stay tuned!

Using Twig in Eleventy (11ty) - A Guide

How to use Eleventy with Twig

Getting Started

Setting up your Twig templates