Eleventy (11ty) Skill

Build fast, flexible static sites with Eleventy's zero-JS-by-default approach and powerful data cascade.

Philosophy Alignment

Eleventy perfectly matches progressive enhancement principles:

Principle	Eleventy Implementation
HTML-first	Outputs pure static HTML
Zero JS by default	No JavaScript unless you add it
Template flexibility	Use any template language
Data-driven	Powerful data cascade system

Project Structure

src/
├── _includes/           # Layouts and partials
│   ├── layouts/
│   │   └── base.njk
│   └── partials/
│       └── header.njk
├── _data/               # Global data files
│   ├── site.json        # Site metadata
│   └── navigation.js    # Dynamic data
├── content/             # Content pages
│   ├── index.njk        # → /
│   ├── about.njk        # → /about/
│   └── blog/
│       ├── blog.json    # Directory data
│       └── post-1.md    # → /blog/post-1/
├── assets/
│   ├── css/
│   └── js/
└── eleventy.config.js   # Configuration

Configuration

javascript

// eleventy.config.js
export default function(eleventyConfig) {
  // Copy static assets
  eleventyConfig.addPassthroughCopy('src/assets');

  // Watch for changes
  eleventyConfig.addWatchTarget('src/assets/css/');

  // Add filters
  eleventyConfig.addFilter('dateFormat', (date, format) => {
    return new Intl.DateTimeFormat('en-US', {
      dateStyle: format || 'medium'
    }).format(date);
  });

  // Add shortcodes
  eleventyConfig.addShortcode('year', () => `${new Date().getFullYear()}`);

  // Add collections
  eleventyConfig.addCollection('posts', (collectionApi) => {
    return collectionApi
      .getFilteredByGlob('src/content/blog/*.md')
      .filter(post => !post.data.draft)
      .sort((a, b) => b.date - a.date);
  });

  return {
    dir: {
      input: 'src',
      output: '_site',
      includes: '_includes',
      data: '_data',
    },
    markdownTemplateEngine: 'njk',
    htmlTemplateEngine: 'njk',
  };
}

Data Cascade

Data flows from global to specific, with later values overriding earlier:

1. Global Data (_data/*.json, _data/*.js)
2. Directory Data (blog/blog.json)
3. Template Front Matter
4. Computed Data

Global Data

json

// src/_data/site.json
{
  "title": "My Website",
  "description": "A website built with Eleventy",
  "url": "https://example.com",
  "author": {
    "name": "Your Name",
    "email": "you@example.com"
  }
}

javascript

// src/_data/navigation.js
export default [
  { text: 'Home', url: '/' },
  { text: 'About', url: '/about/' },
  { text: 'Blog', url: '/blog/' },
];

Directory Data

Apply data to all files in a directory:

json

// src/content/blog/blog.json
{
  "layout": "layouts/post.njk",
  "tags": ["posts"],
  "permalink": "/blog/{{ page.fileSlug }}/"
}

Front Matter

yaml

---
title: My Blog Post
description: A description of this post
date: 2024-01-15
tags:
  - javascript
  - tutorial
draft: false
---

Template Languages

Nunjucks (.njk)

Primary recommended template language:

nunjucks

{# src/_includes/layouts/base.njk #}
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8"/>
  <meta name="viewport" content="width=device-width, initial-scale=1"/>
  <meta name="description" content="{{ description or site.description }}"/>
  <title>{{ title }} | {{ site.title }}</title>
  <link rel="stylesheet" href="/assets/css/main.css"/>
</head>
<body>
  {% include "partials/header.njk" %}

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

  {% include "partials/footer.njk" %}
</body>
</html>

Conditionals and Loops

nunjucks

{# Conditionals #}
{% if featured %}
  <span class="badge">Featured</span>
{% endif %}

{% if posts.length %}
  <ul>
    {% for post in posts %}
      <li>
        <a href="{{ post.url }}">{{ post.data.title }}</a>
        <time datetime="{{ post.date | dateFormat }}">
          {{ post.date | dateFormat }}
        </time>
      </li>
    {% endfor %}
  </ul>
{% else %}
  <p>No posts yet.</p>
{% endif %}

Macros (Reusable Components)

nunjucks

{# src/_includes/macros/card.njk #}
{% macro card(title, href, description) %}
<article class="card">
  <h2><a href="{{ href }}">{{ title }}</a></h2>
  {% if description %}
    <p>{{ description }}</p>
  {% endif %}
</article>
{% endmacro %}

{# Usage #}
{% from "macros/card.njk" import card %}

{{ card(
  title="My Post",
  href="/blog/my-post/",
  description="A brief description"
) }}

Collections

Group content for listing pages:

javascript

// eleventy.config.js
eleventyConfig.addCollection('posts', (collectionApi) => {
  return collectionApi.getFilteredByGlob('src/content/blog/**/*.md');
});

// Tag-based collection (automatic)
// Any content with `tags: posts` in front matter
eleventyConfig.addCollection('posts', (collectionApi) => {
  return collectionApi.getFilteredByTag('posts');
});

Using Collections

nunjucks

{# List all posts #}
<ul>
{% for post in collections.posts %}
  <li>
    <a href="{{ post.url }}">{{ post.data.title }}</a>
  </li>
{% endfor %}
</ul>

{# Paginate posts #}
---
pagination:
  data: collections.posts
  size: 10
  alias: posts
---

{% for post in posts %}
  ...
{% endfor %}

{# Pagination navigation #}
{% if pagination.href.previous %}
  <a href="{{ pagination.href.previous }}">Previous</a>
{% endif %}
{% if pagination.href.next %}
  <a href="{{ pagination.href.next }}">Next</a>
{% endif %}

Filters

Built-in and custom filters:

javascript

// eleventy.config.js

// Date formatting
eleventyConfig.addFilter('dateFormat', (date, format = 'medium') => {
  return new Intl.DateTimeFormat('en-US', { dateStyle: format }).format(date);
});

// Reading time
eleventyConfig.addFilter('readingTime', (content) => {
  const words = content.split(/\s+/).length;
  const minutes = Math.ceil(words / 200);
  return `${minutes} min read`;
});

// Limit array
eleventyConfig.addFilter('limit', (arr, limit) => arr.slice(0, limit));

// Excerpt
eleventyConfig.addFilter('excerpt', (content, length = 200) => {
  const text = content.replace(/<[^>]+>/g, '');
  return text.length > length ? text.slice(0, length) + '...' : text;
});

nunjucks

{# Usage #}
<time>{{ post.date | dateFormat('long') }}</time>
<span>{{ post.content | readingTime }}</span>
<p>{{ post.content | excerpt(150) }}</p>

{% for post in collections.posts | limit(5) %}
  ...
{% endfor %}

Shortcodes

Reusable content snippets:

javascript

// eleventy.config.js

// Simple shortcode
eleventyConfig.addShortcode('year', () => `${new Date().getFullYear()}`);

// Paired shortcode (with content)
eleventyConfig.addPairedShortcode('callout', (content, type = 'info') => {
  return `<aside class="callout callout--${type}">${content}</aside>`;
});

// Async shortcode (for fetching data)
eleventyConfig.addAsyncShortcode('image', async (src, alt) => {
  // Image optimization logic here
  return `<img src="${src}" alt="${alt}" loading="lazy"/>`;
});

nunjucks

{# Usage #}
<p>Copyright {% year %}</p>

{% callout "warning" %}
  This is a warning message.
{% endcallout %}

{% image "hero.jpg", "A descriptive alt text" %}

Permalinks

Control output URLs:

yaml

---
# Static permalink
permalink: /custom-url/

# Dynamic permalink
permalink: /blog/{{ page.date | date: '%Y/%m' }}/{{ page.fileSlug }}/

# Disable output (data-only file)
permalink: false

# Multiple outputs (feeds)
permalink:
  - /feed.xml
  - /feed.json
---

RSS Feed

nunjucks

{# src/feed.njk #}
---
permalink: /feed.xml
eleventyExcludeFromCollections: true
---
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>{{ site.title }}</title>
  <link href="{{ site.url }}/feed.xml" rel="self"/>
  <link href="{{ site.url }}/"/>
  <updated>{{ collections.posts[0].date | dateFormat }}</updated>
  <id>{{ site.url }}/</id>
  <author>
    <name>{{ site.author.name }}</name>
  </author>
  {% for post in collections.posts | limit(10) %}
  <entry>
    <title>{{ post.data.title }}</title>
    <link href="{{ site.url }}{{ post.url }}"/>
    <updated>{{ post.date | dateFormat }}</updated>
    <id>{{ site.url }}{{ post.url }}</id>
    <content type="html">{{ post.content | escape }}</content>
  </entry>
  {% endfor %}
</feed>

Deployment

Cloudflare Pages

bash

# Build command
npx @11ty/eleventy

# Output directory
_site

DigitalOcean App Platform

yaml

# .do/app.yaml
name: my-eleventy-site
static_sites:
  - name: web
    source_dir: /
    build_command: npm run build
    output_dir: _site

Checklist

Before deploying:

Global data in _data/ is complete
Collections are properly configured
Permalinks generate correct URLs
RSS feed validates
Images have alt text
Build succeeds: npx @11ty/eleventy
Output is correct in _site/

Related Skills

xhtml-author - HTML patterns for templates
markdown-author - Content authoring
css-author - Styling patterns
deployment - Cloudflare and DigitalOcean
performance - Static site optimization

Search AI Tools

eleventy

Install this agent skill to your Project

SKILL.md

Eleventy (11ty) Skill

Philosophy Alignment

Project Structure

Configuration

Data Cascade

Global Data

Directory Data

Front Matter

Template Languages

Nunjucks (.njk)

Conditionals and Loops

Macros (Reusable Components)

Collections

Using Collections

Filters

Shortcodes

Permalinks

RSS Feed

Deployment

Cloudflare Pages

DigitalOcean App Platform

Checklist

Related Skills