Eleventy Template Engine Selection: A Practical Guide for Blog Sites

Choose the Right Template Engine for Your Eleventy Blog

If you're building a blog with Eleventy, one of the first architectural decisions you'll face is selecting a template engine. This choice affects build performance, developer experience, and how you structure your content. The wrong choice can lead to frustrating debugging sessions or unnecessarily complex templates.

Eleventy Template Engines Compared

Engine	Learning Curve	Logic Support	File Extension	Best For
Nunjucks	Low	Full	.njk	Complex layouts with filters and async rendering
Liquid	Very Low	Basic	.liquid	Shopify‑style simplicity, untrusted content
Handlebars	Low	Limited helpers	.hb	Semantic templates with custom helpers
Markdown	None	None	.md	Pure content with front matter

Trade‑Offs Explained

Nunjucks provides the most power with filters, macros, and asynchronous rendering. However, this power comes with a small build‑time overhead. The engine processes {% %} tags efficiently but requires careful handling of async operations.

Liquid is the fastest and safest option, especially when dealing with untrusted content. It lacks advanced control structures like loops with complex conditions, making it better suited for simpler templating needs.

Handlebars strikes a balance between simplicity and extensibility. Helpers allow you to add custom logic, but the engine doesn't support as many built‑in features as Nunjucks.

Markdown is ideal for content‑only files. It requires front matter for any layout or variable injection, making it less flexible for complex site structures.

Concrete Implementation with Nunjucks

Create your .eleventy.js configuration file:

module.exports = function(eleventyConfig) {
  // Set template formats to process
  eleventyConfig.setTemplateFormats(['njk', 'md', 'html']);

  // Copy static assets
  eleventyConfig.addPassthroughCopy({'src/img': 'img'});

  return {
    dir: {
      input: 'src',
      output: '_site'
    }
  };
};

Next, create a base layout at src/_includes/base.njk:

<!DOCTYPE html>
<html>
<head>
  <title>{{ title }} | My Blog</title>
</head>
<body>
  {{ content | safe }}
</body>
</html>

Finally, create a page at src/index.md with front matter:

---
layout: base.njk
title: Home
---
# Welcome to my blog

This is my first post using Eleventy.

Validation Checklist

1. Run the build: Execute npx @11ty/eleventy from your project root. Check for errors in the console output.
2. Serve locally: Run npx @11ty/eleventy --serve and open http://localhost:8080. Verify that Nunjucks tags like {% set title %} are processed correctly.
3. Inspect output: Open _site/index.html and confirm that the title appears in the <title> tag and the markdown content is converted to HTML paragraphs.
4. Check assets: Verify that images in src/img are copied to _site/img.

Version Requirements and Limitations

These examples assume Eleventy v2.0 or later. Older versions may lack the setTemplateFormats API or have different default extensions. Always check your version with npx @11ty/eleventy --version.

When using Nunjucks with asynchronous filters, remember to await them in templates. Otherwise, rendering may complete before async work finishes, resulting in missing output.

Quick Verification Commands

# Check Eleventy version
npx @11ty/eleventy --version

# Run build and check for errors
npx @11ty/eleventy

# Serve locally for testing
npx @11ty/eleventy --serve

# Debug template loading
npx @11ty/eleventy --debug

If your test suite includes assertions, run npm test to validate file existence and content patterns against known good snapshots.