Eleventy Documentation

WebC

2026-09-08T13:31:37Z

On this page

Type	Value
Eleventy Name	`webc`
File Extension	`*.webc`
npm	`@11ty/webc` and `@11ty/eleventy-plugin-webc`
GitHub	`11ty/webc` and `11ty/eleventy-plugin-webc`

Why use WebC?

Brings first-class components to Eleventy.
- Expand any HTML element (including custom elements) to HTML with defined conventions from web standards.
- This means that Web Components created with WebC are compatible with server-side rendering (without duplicating author-written markup)
- WebC components are Progressive Enhancement friendly.

Performance

Create streamlined component-driven, cache-friendly page-specific JavaScript and CSS bundles. Users load only the code they need to render that page (or that island).
- Easily configurable boundaries for critical component CSS and JavaScript.
- Works great with is-land for web component hydration.
Get first-class incremental builds (for page templates, components, and Eleventy layouts) when used with --incremental
Streaming friendly (stream on the Edge 👀)

Compatible with Standards

Uses parse5 to parse WebC HTML as modern browsers do (a nod to @DasSurma’s work with Vite here)
Shadow DOM and Declarative Shadow DOM friendly (easily switch components between Light DOM and Shadow DOM)

Authoring

Encourages no-quirks mode HTML authoring (and a doctype is optional). WebC throws a helpful error if it encounters quirks mode markup.
Easily scope component CSS (or use your own scoping utility).
Tired of importing components? Use global or per-page no-import components.
Async-friendly: All configuration extensions/hooks into WebC are async-friendly out of the box.
For more complex templating needs, render any existing Eleventy template syntax (Liquid, markdown, Nunjucks, etc.) inside of WebC.

Resources

Introduction to WebC (11ty.rocks) by W. Evan Sheehan
Understanding WebC Features and Concepts (11ty.rocks) by Stephanie Eckles
WebC Number Counter Example Source Code and Demo
Seven Demos of Progressive Enhancement using Image Comparison Components and Source Code
First Experience Building with Eleventy's WebC Plugin

zachleat.com: Adding Components to Eleventy with WebC: a brief history of the motivation behind WebC including influences from the Svelte and Vue communities.
11ty.webc.fun: a collection of WebC recipes!
Robin Cussol: Optimize your img tags with Eleventy Image and WebC

Installation

Note that WebC support in Eleventy is not bundled with core! You must install the officially supported Eleventy plugin and the plugin requires Eleventy v2.0.0 or newer.

It’s on npm at @11ty/eleventy-plugin-webc!

npm install @11ty/eleventy-plugin-webc

To add support for .webc files in Eleventy, add the plugin in your Eleventy configuration file:

eleventy.config.js

ESM CommonJS

import pluginWebc from "@11ty/eleventy-plugin-webc";

export default function(eleventyConfig) {
	eleventyConfig.addPlugin(pluginWebc);
};

const pluginWebc = require("@11ty/eleventy-plugin-webc");

module.exports = function(eleventyConfig) {
	eleventyConfig.addPlugin(pluginWebc);
};

Full options list (defaults shown)

eleventy.config.js

ESM CommonJS

import pluginWebc from "@11ty/eleventy-plugin-webc";

export default function (eleventyConfig) {
	eleventyConfig.addPlugin(pluginWebc, {
		// Glob to find no-import global components
		// (The default changed from `false` in Eleventy WebC v0.7.0)
		components: "_components/**/*.webc",

		// Adds an Eleventy WebC transform to process all HTML output
		useTransform: false,

		// Additional global data used in the Eleventy WebC transform
		transformData: {},

		// Options passed to @11ty/eleventy-plugin-bundle
		bundlePluginOptions: {},
	});
};

const pluginWebc = require("@11ty/eleventy-plugin-webc");

module.exports = function (eleventyConfig) {
	eleventyConfig.addPlugin(pluginWebc, {
		// Glob to find no-import global components
		// (The default changed from `false` in Eleventy WebC v0.7.0)
		components: "_components/**/*.webc",

		// Adds an Eleventy WebC transform to process all HTML output
		useTransform: false,

		// Additional global data used in the Eleventy WebC transform
		transformData: {},

		// Options passed to @11ty/eleventy-plugin-bundle
		bundlePluginOptions: {},
	});
};

View the full options list for the Bundle plugin. As an example, you can use the transforms array to modify bundle content with postcss.

Syntax highlighting

Because WebC is HTML, you can configure your editor to treat .webc files as HTML for syntax highlighting. Your editor of choice should have some documentation on how to get this working.

Usage

There are a few different ways to use WebC in Eleventy:

Add a new `.webc` file

Adding the plugin enables support for .webc files in your Eleventy project. Create a new .webc HTML file in your Eleventy input directory and Eleventy processes it for you. .webc files operate in WebC bundler mode, aggregating the CSS and JS in use on each individual page into a bundle of the assets in use on the page.

WebC uses an HTML parser to process input files: use any HTML here!

Filename my-page.webc

<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="utf-8" />
		<title>WebC Example</title>
	</head>
	<body>
		WebC *is* HTML.
	</body>
</html>

Non-traditional WebC usage

Use the Render plugin

Using Eleventy’s built-in Render plugin allows you to render WebC inside of an existing Liquid, Nunjucks, or 11ty.js template.

Liquid Nunjucks 11ty.js 11ty.cjs

{% renderTemplate "webc" %}
<my-custom-component></my-custom-component>
{% endrenderTemplate %}

{% renderTemplate "webc" %}
<my-custom-component></my-custom-component>
{% endrenderTemplate %}

export default async function () {
	let content = await this.renderTemplate(
		`<my-custom-component></my-custom-component>`,
		"webc"
	);
	return content;
};

module.exports = async function () {
	let content = await this.renderTemplate(
		`<my-custom-component></my-custom-component>`,
		"webc"
	);
	return content;
};

Pre-process HTML input as WebC

You can use the configuration option to change the default HTML preprocessor (from liquid) to webc. This might look like htmlTemplateEngine: "webc". Read more on the Eleventy documentation: Default Template Engine for HTML Files.

Post-process HTML output as WebC

This is a catch-all option that lets WebC process .html output files in your project (skipping any .webc input files to avoid double-processing templates). It uses Eleventy transforms and is most useful when you want to get up and running with WebC on an existing project quickly.

A few drawbacks to the transform method:

This is the slowest build-performance method to implement WebC in a project, so try the other methods first!
The WebC Eleventy transform operates with bundler mode disabled, which means it processes WebC but does not aggregate component JS or CSS. (Upvote this enhancement request)

The transform is disabled by default, you will need to use the useTransform option to enable it.

eleventy.config.js

ESM CommonJS

import pluginWebc from "@11ty/eleventy-plugin-webc";

export default function (eleventyConfig) {
	eleventyConfig.addPlugin(pluginWebc, {
		useTransform: true,
	});
};

const pluginWebc = require("@11ty/eleventy-plugin-webc");

module.exports = function (eleventyConfig) {
	eleventyConfig.addPlugin(pluginWebc, {
		useTransform: true,
	});
};

Components and output

HTML-only components

Related: Defining Components in WebC

When WebC does not find <style>, <link rel="stylesheet">, or <script> elements a component file, WebC leaves the host component tag out of the output HTML by default. To keep the component tags in the output, add webc:keep to the host component.

WebC components are not limited to custom element name restrictions (e.g. my-component) here. You can use p, blockquote, h1, img, or any valid HTML tag name.

Default behavior With webc:keep

Filename _components/my-component.webc

Hello possum.

Filename index.webc

<!DOCTYPE html>
<title>WebC Example</title>
<my-component></my-component>

Output example _site/index.html

<!DOCTYPE html>
<html>
	<head>
		<title>WebC Example</title>
	</head>
	<body>
		Hello possum.
	</body>
</html>

Filename _components/my-component.webc

Hello possum.

Filename index.webc

<!DOCTYPE html>
<title>WebC Example</title>
<my-component webc:keep></my-component>

Output example _site/index.html

<!DOCTYPE html>
<html>
	<head>
		<title>WebC Example</title>
	</head>
	<body>
		<my-component>Hello possum.</my-component>
	</body>
</html>

Asset bundling

When WebC finds <style>, <link rel="stylesheet">, or <script> elements in a component file, WebC includes the host component tag in the output HTML by default, so you can style it or reach it from client scripts. To drop the component tag from the output, add webc:nokeep to the host component.

This example also shows how Eleventy automatically bundles scripts and styles, learn more about CSS and JS in WebC.

Default behavior With webc:nokeep

Filename _components/my-component.webc

<p class="possum">Hello possum.</p>
<style>
	.possum { color: rebeccapurple }
</style>

Filename index.webc

<!DOCTYPE html>
<title>WebC Example</title>
<style @raw="getBundle('css')" webc:keep></style>
<my-component></my-component>

Output example _site/index.html

<!DOCTYPE html>
<html>
	<head>
		<title>WebC Example</title>
		<style>.possum { color: rebeccapurple }</style>
	</head>
	<body>
		<my-component><p class="possum">Hello possum.</p></my-component>
	</body>
</html>

Filename _components/my-component.webc

<p class="possum">Hello possum.</p>
<style>
	.possum { color: rebeccapurple }
</style>

Filename index.webc

<!DOCTYPE html>
<title>WebC Example</title>
<style @raw="getBundle('css')" webc:keep></style>
<my-component webc:nokeep></my-component>

Output example _site/index.html

<!DOCTYPE html>
<html>
	<head>
		<title>WebC Example</title>
		<style>.possum { color: rebeccapurple }</style>
	</head>
	<body>
		<p class="possum">Hello possum.</p>
	</body>
</html>

`webc:keep`

Keeps the host tag of an HTML-only component in the output.

Filename index.webc

<my-html-only-component webc:keep></my-html-only-component>

Keeps a <style>, <link rel="stylesheet">, or <script> element as written in the output instead of adding it to the bundle.

Filename _components/my-component.webc

<!-- without webc:keep, WebC removes these from the output
     and adds their content to the page’s CSS and JS bundles -->
<style webc:keep>
	.possum { color: rebeccapurple }
</style>
<script webc:keep>
	console.log("Hello possum.");
</script>

Keeps a <slot> element in the output for a client-side custom element to fill. Read more at Slots.

`webc:nokeep`

Drops the host tag of a component with CSS or JavaScript from the output.

Filename index.webc

<my-stylish-component webc:nokeep></my-stylish-component>

Inserts content into the output as-is, without adding an element around it.

Filename _includes/layout.webc

<template @raw="content" webc:nokeep></template>

`webc:is`

Replaces the element’s tag name with a component name. Both examples are equivalent to <my-component></my-component>.

Filename index.webc

<div webc:is="my-component"></div>

<div
  webc:is="my-component"
	webc:import="./some-other-directory/my-component.webc"
></div>

`webc:import`

Imports the component definition for the element from a path relative to the current file, or from an npm package with the npm: prefix.

Note: WebC expands any component it already knows about without an import, such as every file matching the default _components/**/*.webc glob.

Related: Defining Components in WebC (global or scoped)

Filename index.webc

<my-component
  webc:import="./some-other-directory/my-component.webc"
></my-component>

<syntax-highlight
	language="js"
	webc:import="npm:@11ty/eleventy-plugin-syntaxhighlight"
>
	function myFunction() { return true; }
</syntax-highlight>

Added in @11ty/webc@0.6.2With the npm: prefix, WebC uses the tag name (syntax-highlight) to look for a component at node_modules/@11ty/eleventy-plugin-syntaxhighlight/syntax-highlight.webc. This also works with a tag name override via webc:is. Eleventy plugins can supply WebC components this way. See the Syntax Highlighter plugin (4.2.0 or newer) for an example.

Attributes, props and slots

Which one to use

Attributes and props pass values into a component and are available inside it as variables by name (camelCased). Slots pass child markup. They differ in how the value is evaluated and whether it reaches the output HTML.

Syntax	Value	In output	Use when
Attribute	String	Yes*	The value belongs on an element in the output, such as `id`, `class`, or `data-*`.
Prop	String	No	The component needs the value but it should not appear in the HTML.
Dynamic attribute	Any JavaScript value	Yes*	The attribute value comes from page data or an expression.
Dynamic prop	Any JavaScript value	No	Pass page data or a non-string value (number, object, array) into the component.
Slot	HTML	Yes**	The page supplies markup, not just a value, or the component wraps arbitrary content.

* Rendered when the host tag is kept in the output, or when the component places them with webc:root or @attributes.
** Rendered where the component places its <slot>.

Attributes and `webc:root`

Attributes on a host component are available inside the component definition. webc:root merges the element’s attributes onto the host component tag, and keeps that tag in the output even for an HTML-only component. WebC merges the class and style attribute values from both.

Filename _components/my-component.webc

<template webc:root class="possum">Hello possum.</template>

Filename index.webc

<my-component class="item"></my-component>

Output example _site/index.html

<my-component class="item possum">Hello possum.</my-component>

Note: The webc:root element must be at the top level of the component definition. Nested inside another element, it has no effect.

Override the host component tag

webc:root="override" replaces the host component tag with the element itself, with the attributes merged.

Filename _components/my-component.webc

<button webc:root="override" class="possum">Hello possum.</button>

Filename index.webc

<my-component class="item"></my-component>

Output example _site/index.html

<button class="possum item">Hello possum.</button>

Added in @11ty/webc@0.9.0Previously, this required webc:root and webc:keep together on an element.

Props (Properties)

Any attribute prefixed with @ becomes a prop: a server-only attribute that the component reads by name and that WebC removes from the output HTML.

Filename _components/story-card.webc

<div class="story-card">
	<h1 @text="title"></h1>
	<p @text="publication"></p>
</div>

Filename index.webc

<story-card
	@title="Top 10 Fashionable Possums"
	@publication="Possum Times"
></story-card>

Output example _site/index.html

<div class="story-card">
	<h1>Top 10 Fashionable Possums</h1>
	<p>Possum Times</p>
</div>

In the HTML specification, attribute names are lower-case. Added in @11ty/webc@0.8.0WebC converts attribute and prop names with dashes (i.e. @author-name) to camelCase for JavaScript (i.e. authorName), so <story-card @author-name="Susan Possum"></story-card> is accessed within the component as <p @text="authorName"></p>. More at issue #71.

Dynamic attributes and properties

A colon (:) prefix makes the value of an attribute or prop a JavaScript expression instead of a string. The expression has access to host component attributes, props, and page data.

This example extends the props example: the title prop and the href attribute now read from page data.

Filename _components/story-card.webc

<div class="story-card">
	<h1 @text="title"></h1>
	<p @text="publication"></p>
	<a :href="href">Read more</a>
</div>

Filename top-ten.webc

---
title: Top 10 Fashionable Possums
---
<story-card
	:@title="title"
	@publication="Possum Times"
	:href="page.url"
></story-card>

Output example _site/top-ten.html

<div class="story-card">
	<h1>Top 10 Fashionable Possums</h1>
	<p>Possum Times</p>
	<a href="/top-ten.html">Read more</a>
</div>

Added in @11ty/webc@0.9.0The :@ prefix for dynamic props.
WebC converts names with dashes to camelCase, as with props.
webc:bucket is currently the only webc:* attribute that accepts a dynamic value. Follow #143 and #148 for more.

`@attributes`

Added in @11ty/webc@0.9.0Renders the host component’s attributes on the element. Props are not included, so @attributes is a way to pass through attributes like id or data-* without listing each one.

Filename _components/story-card.webc

<div class="story-card" @attributes>
	<h1 @text="title"></h1>
	<p @text="publication"></p>
</div>

Filename index.webc

<story-card
	@title="Top 10 Fashionable Possums"
	@publication="Possum Times"
	id="top-story"
	data-story-id="42"
></story-card>

Output example _site/index.html

<div class="story-card" id="top-story" data-story-id="42">
	<h1>Top 10 Fashionable Possums</h1>
	<p>Possum Times</p>
</div>

A host attribute with the same name as one on the element replaces it: class="featured" on <story-card> would replace class="story-card" in the output. To merge class and style values instead, use webc:root on the element in the component file in place of @attributes (e.g. <div class="story-card" webc:root>).

Given a value, @attributes renders each entry of a JavaScript object as an attribute instead.

Filename _components/story-card.webc

<div @attributes="({ class: 'story-card', id: `story-${storyId}` })"></div>

Filename index.webc

<story-card @story-id="42"></story-card>

Output example _site/index.html

<div class="story-card" id="story-42"></div>

Wrap the object in parentheses so JavaScript does not parse it as a block with a label. Without a value, @attributes is shorthand for @attributes="webc.attributes".

Slots

WebC places the child content of a component using <slot> and [slot], following web component conventions. This example uses an HTML-only component.

Filename _components/my-component.webc

<p><slot>This text is the default fallback.</slot></p>

Filename index.webc

<!-- example with content -->
<my-component>This text will replace slot.</my-component>

<!-- example with fallback -->
<my-component></my-component>

Output example _site/index.html

<!-- example with content -->
<p>This text will replace slot.</p>

<!-- example with fallback -->
<p>This text is the default fallback.</p>

To output a <slot> element in the compiled markup (for use in client JavaScript), add the webc:keep attribute to it (e.g. <slot webc:keep>).

If your component file contains no content markup (it is empty, or has only <style> or <script> elements), WebC implies <slot></slot> and includes the default slot content automatically, per web component conventions. If the component file does contain content markup, include <slot> to place the default slot content.

Named slots

Named slots (e.g. <h1 slot="title">) work too. Each [slot] element is placed at the <slot> with the matching name. This example passes the same content as the props example through slots instead.

Filename _components/story-card.webc

<div class="story-card">
	<slot name="title"></slot>
	<slot name="publication"></slot>
</div>

Filename index.webc

<story-card>
	<h1 slot="title">Top 10 Fashionable Possums</h1>
	<p slot="publication">Possum Times</p>
</story-card>

Output example _site/index.html

<div class="story-card">
	<h1>Top 10 Fashionable Possums</h1>
	<p>Possum Times</p>
</div>

Rendering content

`@html`

Replaces the element’s content with the result of a JavaScript expression, processed as WebC. To skip that processing, use @raw. Like other props, WebC removes the prop key from the output. Add webc:nokeep to output the result without the element.

Filename index.webc

---
summary: "A <em>very</em> fashionable possum."
---
<p @html="summary"></p>
<template @html="summary" webc:nokeep></template>

Output example _site/index.html

<p>A <em>very</em> fashionable possum.</p>
A <em>very</em> fashionable possum.

Added in @11ty/webc@0.5.0WebC processes the returned content as WebC, so you can return any WebC content here.

`@raw`

Added in @11ty/webc@0.7.1Replaces the element’s content with the result of a JavaScript expression without reprocessing it as WebC. This is a shorthand for webc:raw @html. A common use is placing the page content in an Eleventy layout.

Added in @11ty/webc@0.6.0Before @raw, add webc:raw to an @html element to prevent processing the result as WebC. webc:raw @html still works.

Filename _includes/layout.webc

<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="utf-8">
		<title>WebC Example</title>
	</head>
	<body>
		<template @raw="content" webc:nokeep></template>
	</body>
</html>

Filename index.webc

---
layout: layout.webc
---
<p>Hello possum.</p>

Output example _site/index.html

<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="utf-8">
		<title>WebC Example</title>
	</head>
	<body>
		<p>Hello possum.</p>
	</body>
</html>

In a layout, content is the page’s finished output. Whether to place it with @raw or @html depends on the template language of the pages that use the layout:

.webc pages are already processed by WebC, so use @raw="content" to place the output as-is.
Pages in another template language, such as Markdown or Nunjucks, are not processed by WebC on their own, so any WebC components or props in their output reach the layout unrendered. Use @html="content" to give them their single WebC pass.
A mix of both can share one layout by branching on the page’s input path:

<template webc:if="page.inputPath.endsWith('.webc')" @raw="content" webc:nokeep></template>
<template webc:else @html="content" webc:nokeep></template>

`@text`

Added in @11ty/webc@0.6.0Replaces the element’s content with the HTML-escaped result of a JavaScript expression. Add webc:nokeep to output the text without the element.

Filename index.webc

---
title: Top 10 Fashionable Possums
summary: A <em>very</em> fashionable possum collection.
possum: Susan
---
<h1 @text="title"></h1>
<!-- given the content, summary should use @html,
     but let's use @text and check the result -->
<p @text="summary"></p>
<template @text="possum" webc:nokeep></template>

Output example _site/index.html

<h1>Top 10 Fashionable Possums</h1>
<!-- given the content, summary should use @html,
     but let's use @text and check the result -->
<p>A &lt;em&gt;very&lt;/em&gt; fashionable possum collection.</p>
Susan

`webc:if`

Added in @11ty/webc@0.7.1Renders the element only when the JavaScript expression in its value is truthy at build time. Like dynamic attributes, the expression has access to component attributes, props, and page data. If the expression returns a promise, WebC awaits it before the check.

Filename index.webc

---
title: Top 10 Fashionable Possums
draft: true
---
<h1 webc:if="title" @text="title"></h1>
<p webc:if="draft">This story is a draft.</p>
<p webc:if="!draft">This story is published.</p>

Output example _site/index.html

<h1>Top 10 Fashionable Possums</h1>
<p>This story is a draft.</p>

For more complex conditional logic, use a webc:type="js" render function.

`webc:elseif` and `webc:else`

Added in @11ty/webc@0.10.0webc:elseif renders the element when the preceding webc:if or webc:elseif sibling did not, and its own JavaScript expression is truthy. webc:else renders the element when no preceding sibling in the chain did. HTML comments between the siblings are allowed.

Filename index.webc

---
possumCount: 3
---
<p webc:if="possumCount > 10">There are many possums!</p>
<p webc:elseif="possumCount > 0">There are some possums.</p>
<p webc:else>There are no possums :(</p>

Output example _site/index.html

<p>There are some possums.</p>

`webc:for`

Added in @11ty/webc@0.10.0Repeats the element for each entry of an iterable (Array, String, Map, Set, and others) or an object, using JavaScript for syntax. Use of for iterables and in for objects. You can name the loop variables whatever you like. A second loop variable receives the zero-based index.

Filename index.webc

---
possums:
  - Susan
  - Finn
  - Jake
---
<ol>
	<li webc:for="name of possums" @text="name"></li>
</ol>
<ul>
	<li webc:for="(name, index) of possums" @text="`${index}: ${name}`"></li>
</ul>

Output example _site/index.html

<ol>
	<li>Susan</li>
	<li>Finn</li>
	<li>Jake</li>
</ol>
<ul>
	<li>0: Susan</li>
	<li>1: Finn</li>
	<li>2: Jake</li>
</ul>

Each entry can be an object. This example renders a table row per possum.

Filename index.webc

---
possums:
  - { name: Susan, hobby: Being strong }
  - { name: Finn, hobby: Dungeon crawling }
---
<table>
	<thead>
		<tr>
			<th>Name</th>
			<th>Hobby</th>
		</tr>
	</thead>
	<tbody>
		<tr webc:for="possum of possums">
			<td @text="possum.name"></td>
			<td @text="possum.hobby"></td>
		</tr>
	</tbody>
</table>

Output example _site/index.html

<table>
	<thead>
		<tr>
			<th>Name</th>
			<th>Hobby</th>
		</tr>
	</thead>
	<tbody>
		<tr>
			<td>Susan</td>
			<td>Being strong</td>
		</tr>
		<tr>
			<td>Finn</td>
			<td>Dungeon crawling</td>
		</tr>
	</tbody>
</table>

Use in for a plain object, such as when you want to list its properties without knowing the keys ahead of time. The loop variables receive the key, the value, and the zero-based index ((key, value, index) in possum).

Filename index.webc

---
possum: { name: Susan, hobby: Being strong }
---
<table>
	<tbody>
		<tr webc:for="(key, value) in possum">
			<th @text="key"></th>
			<td @text="value"></td>
		</tr>
	</tbody>
</table>

Output example _site/index.html

<table>
	<tbody>
		<tr>
			<th>name</th>
			<td>Susan</td>
		</tr>
		<tr>
			<th>hobby</th>
			<td>Being strong</td>
		</tr>
	</tbody>
</table>

To repeat several elements at once, loop on a <template> with webc:nokeep.

Filename index.webc

---
possums:
  - { name: Susan, hobby: Being strong }
  - { name: Finn, hobby: Dungeon crawling }
---
<dl>
	<template webc:for="possum of possums" webc:nokeep>
		<dt @text="possum.name"></dt>
		<dd @text="`Hobby: ${possum.hobby}`"></dd>
	</template>
</dl>

Output example _site/index.html

<dl>
	<dt>Susan</dt>
	<dd>Hobby: Being strong</dd>
	<dt>Finn</dt>
	<dd>Hobby: Dungeon crawling</dd>
</dl>

Loops can be nested, but the inner loop cannot access the outer loop’s variables yet. Follow issue #175 for progress.

Scripts and styles

`webc:setup`

Added in @11ty/webc@0.9.0Runs the <script> element once on the server and exposes its top-level declarations as data to the component. Use it to provide data and markup to the rest of the component.

This is similar to using JavaScript as a custom Eleventy front matter type, although data in webc:setup is scoped to the component and does not flow back up into the Data Cascade.

Note: Because this JavaScript runs only once per build, even when the component is used many times, it has no access to instance-specific data such as attributes, props, or slots. A function declared here can still receive that data as arguments when the component calls it, see the second example.

Filename _components/possum-list.webc

<script webc:setup>
	const possums = ["Susan", "Finn", "Jake"];
</script>

<h2 @text="`${possums.length} fashionable possums`"></h2>
<ul>
	<li webc:for="name of possums" @text="name"></li>
</ul>

Filename index.webc

<possum-list></possum-list>

Output example _site/index.html

<h2>3 fashionable possums</h2>
<ul>
	<li>Susan</li>
	<li>Finn</li>
	<li>Jake</li>
</ul>

To use instance-specific data, declare a function in the setup script and pass the attributes or props in as arguments from the component markup.

Filename _components/possum-greeting.webc

<script webc:setup>
	function greeting(name, hobby) {
		return `Hello ${name}, do you enjoy ${hobby.toLowerCase()}?`;
	}
</script>

<p @text="greeting(name, hobby)"></p>

Filename index.webc

<possum-greeting @name="Susan" @hobby="Being strong"></possum-greeting>
<possum-greeting @name="Finn" @hobby="Dungeon crawling"></possum-greeting>

Output example _site/index.html

<p>Hello Susan, do you enjoy being strong?</p>
<p>Hello Finn, do you enjoy dungeon crawling?</p>

Works with var, let, const, function, and Array and Object destructuring assignment. Uses the node-retrieve-globals package.

`webc:type`

Treats the element’s content as a JavaScript render function (js), or as another Eleventy template syntax (11ty, named in 11ty:type). The Eleventy WebC plugin bundles four types:

webc:type="js" Added in @11ty/webc@0.7.1
webc:type="render" (superseded by webc:type="js")
webc:type="11ty" (Eleventy only)
webc:type="css:scoped" (internal, used by webc:scoped, but overridable)

Adding your own webc:type custom transform directly to WebC is not yet available in the Eleventy WebC plugin. If you would like to see this added, please let us know.

`webc:type="js"`

Added in @11ty/webc@0.7.1Runs the content as server JavaScript. The value of the last statement replaces the element and is processed as WebC. If the value is a promise, WebC resolves it. The script has access to the component’s attributes and props.

With alt Missing alt

Filename _components/img.webc

<script webc:type="js">
	if (!alt) {
		throw new Error(`Missing alt attribute on <img src="${src}">`);
	}
	`<img src="${src}" alt="${alt}">`;
</script>

Filename index.webc

<img src="susan.jpeg" alt="Susan Possum in a purple jacket">

Output example _site/index.html

<img src="susan.jpeg" alt="Susan Possum in a purple jacket">

Filename _components/img.webc

<script webc:type="js">
	if (!alt) {
		throw new Error(`Missing alt attribute on <img src="${src}">`);
	}
	`<img src="${src}" alt="${alt}">`;
</script>

Filename index.webc

<img src="finn.jpeg">

Build error npx @11ty/eleventy

[11ty] Original error message: Missing alt attribute on <img src="finn.jpeg">

The same component with the superseded webc:type="render", which exports a function and reads attributes from this. Unlike js, render does not imply webc:is="template", so add it to drop the void <img> host tag:

Filename _components/img.webc

<script webc:type="render" webc:is="template">
	export default function () {
		if (!this.alt) {
			throw new Error(`Missing alt attribute on <img src="${this.src}">`);
		}
		return `<img src="${this.src}" alt="${this.alt}">`;
	}
</script>

A render function can generate CSS too. Add webc:is="style" and WebC adds the result to the CSS bundle like any other component style.

Filename _components/possum-theme.webc

<script webc:type="js" webc:is="style">
	`.possum { color: ${color}; }`;
</script>

Filename index.webc

<!DOCTYPE html>
<title>WebC Example</title>
<style @raw="getBundle('css')" webc:keep></style>
<possum-theme @color="rebeccapurple"></possum-theme>
<p class="possum">Hello possum.</p>

Output example _site/index.html

<!DOCTYPE html>
<html>
	<head>
		<title>WebC Example</title>
		<style>.possum { color: rebeccapurple; }</style>
	</head>
	<body>
		<possum-theme></possum-theme>
		<p class="possum">Hello possum.</p>
	</body>
</html>

The same component with the superseded webc:type="render":

Filename _components/possum-theme.webc

<script webc:type="render" webc:is="style">
	export default function () {
		return `.possum { color: ${this.color}; }`;
	}
</script>

Notes:

To generate scoped CSS with JavaScript, add webc:scoped to the element as well (<script webc:type="js" webc:is="style" webc:scoped>).
For simple conditions, webc:if may be all you need.
Added in @11ty/webc@0.9.0webc:type="js" implies webc:is="template", so WebC reprocesses the returned content as WebC (HTML). Set your own webc:is attribute to generate a different tag (e.g. webc:is="script" or webc:is="style").
Added in @11ty/webc@0.9.0webc:type="js" implies webc:nokeep, so the outer element is left out of the output. Add webc:keep to keep it.

Extra data for JavaScript render functions

webc.attributes: Added in @11ty/webc@0.9.0 an object literal representing the current element’s attributes.
webc.renderAttributes: Added in @11ty/webc@0.9.0 a method to render public attributes to a string.
webc.filterPublicAttributes: Added in @11ty/webc@0.10.1 a method to filter webc.attributes, returning an object with only public attributes. Usage: webc.filterPublicAttributes(webc.attributes)
webc.escapeText: Added in @11ty/webc@0.10.1 encodes all characters that have to be escaped in HTML text (via the entities package)
webc.escapeAttribute: Added in @11ty/webc@0.10.1 encodes all characters that have to be escaped in HTML attributes (via the entities package)

`webc:type="11ty"` and `11ty:type`

Renders the content with the Eleventy template syntax, or comma-separated chain of syntaxes, named in 11ty:type. The Eleventy WebC plugin wires the WebC custom transforms feature to the Eleventy Render plugin to make this possible.

Note: The webc:type="11ty" feature is exclusive to the Eleventy WebC plugin and is not available in standalone WebC.

11ty:type accepts any valid template syntax.

Filename index.webc

---
title: Top 10 Fashionable Possums
---
<template webc:type="11ty" 11ty:type="liquid,md">
{% assign publication = "Possum Times" %}
## {{ title }}

_{{ publication }}_
</template>

Output example _site/index.html

<h2>Top 10 Fashionable Possums</h2>
<p><em>Possum Times</em></p>

The template has full access to the data cascade, including title set in front matter.
Added in @11ty/webc@0.5.0WebC processes content returned on <template> (or webc:is="template") elements as WebC, so you can return any WebC content here.
You can add your own custom template engine, which is then available here too (e.g. <style webc:type="11ty" 11ty:type="sass">).

Helper functions

WebC helpers are JavaScript functions available in dynamic attributes, @html, @raw, and render functions.

Eleventy-provided helpers

Added in @11ty/eleventy-plugin-webc@0.5.0Eleventy WebC provides JavaScript template functions and universal filters automatically as WebC helpers.

This includes url, slugify, log, and others.

Filename index.webc

<a :href="url('/possums/')">All possums</a>

Output example _site/index.html

<a href="/possums/">All possums</a>

Supply your own helper

eleventy.config.js

ESM CommonJS

export default function (eleventyConfig) {
	// via a universal filter
	eleventyConfig.addFilter("shout", (text) => text.toUpperCase());

	// or via a JavaScript template function directly
	eleventyConfig.addJavaScriptFunction("siteName", () => "Possum Times");
};

module.exports = function (eleventyConfig) {
	// via a universal filter
	eleventyConfig.addFilter("shout", (text) => text.toUpperCase());

	// or via a JavaScript template function directly
	eleventyConfig.addJavaScriptFunction("siteName", () => "Possum Times");
};

Filename index.webc

---
title: Top 10 Fashionable Possums
---
<h1 @text="shout(title)"></h1>
<p @text="siteName()"></p>

Output example _site/index.html

<h1>TOP 10 FASHIONABLE POSSUMS</h1>
<p>Possum Times</p>

`webc:scoped`

Scopes the <style> element to the component by prefixing every selector with a generated class, or with the class name given as the value. The generated class name is a hash of the style content, so WebC de-duplicates identical component styles. WebC replaces :host with the generated class selector.

To choose your own prefix, give webc:scoped a value. Prefer a named prefix when anything outside the component refers to the class, such as other stylesheets, scripts, or tests: the generated name changes whenever you edit the style content, while a named prefix stays the same and keeps the output CSS readable. WebC checks for duplicate prefixes in your component tree and throws an error when it finds a collision.

Default behavior Named prefix

Filename _components/my-component.webc

<style webc:scoped>
	:host {
		color: blue;
	}
	h1 {
		color: rebeccapurple;
	}
</style>
<h1>Top 10 Fashionable Possums</h1>
<p>Hello possum.</p>

Filename index.webc

<!DOCTYPE html>
<title>WebC Example</title>
<style @raw="getBundle('css')" webc:keep></style>
<my-component></my-component>

Output example _site/index.html

<!DOCTYPE html>
<html>
	<head>
		<title>WebC Example</title>
		<style>.wt-d_fkgu{color:blue}.wt-d_fkgu h1{color:rebeccapurple}</style>
	</head>
	<body>
		<my-component class="wt-d_fkgu">
			<h1>Top 10 Fashionable Possums</h1>
			<p>Hello possum.</p>
		</my-component>
	</body>
</html>

Filename _components/my-component.webc

<style webc:scoped="possum">
	:host {
		color: blue;
	}
	h1 {
		color: rebeccapurple;
	}
</style>
<h1>Top 10 Fashionable Possums</h1>
<p>Hello possum.</p>

Filename index.webc

<!DOCTYPE html>
<title>WebC Example</title>
<style @raw="getBundle('css')" webc:keep></style>
<my-component></my-component>

Output example _site/index.html

<!DOCTYPE html>
<html>
	<head>
		<title>WebC Example</title>
		<style>.possum{color:blue}.possum h1{color:rebeccapurple}</style>
	</head>
	<body>
		<my-component class="possum">
			<h1>Top 10 Fashionable Possums</h1>
			<p>Hello possum.</p>
		</my-component>
	</body>
</html>

Declarative Shadow DOM is another way to encapsulate component styles, and you can use both methods in WebC. It has two tradeoffs:

Progressive enhancement requires ubiquitous browser support before you use it for content in the critical rendering path.
It duplicates the <style> element in each instance of the component.

Expand for a Declarative Shadow DOM example

WebC leaves the <style> inside a shadow root template as is, so it is not bundled and repeats in every instance. WebC also fills the <slot> at build time.

Filename _components/my-component.webc

<template shadowrootmode="open">
	<style>
		h1 {
			color: rebeccapurple;
		}
	</style>
	<slot></slot>
</template>

Filename index.webc

<!DOCTYPE html>
<title>WebC Example</title>
<style @raw="getBundle('css')" webc:keep></style>
<my-component>
	<h1>Top 10 Fashionable Possums</h1>
</my-component>
<my-component>
	<h1>Hello possum.</h1>
</my-component>

Output example _site/index.html

<!DOCTYPE html>
<html>
	<head>
		<title>WebC Example</title>
		<style></style>
	</head>
	<body>
		<my-component>
			<template shadowrootmode="open">
				<style>
					h1 {
						color: rebeccapurple;
					}
				</style>
				<h1>Top 10 Fashionable Possums</h1>
			</template>
		</my-component>
		<my-component>
			<template shadowrootmode="open">
				<style>
					h1 {
						color: rebeccapurple;
					}
				</style>
				<h1>Hello possum.</h1>
			</template>
		</my-component>
	</body>
</html>

`webc:bucket`

Sends the element’s bundled CSS or JavaScript to a named asset bucket instead of the default one, so you can output it somewhere else on the page, for example at the end of <body> instead of in <head>. Output a bucket with getBundle(type, name). Read more at Asset bucketing.

On the element Cascading from a parent

Filename _components/my-footer.webc

<style>
	footer { color: rebeccapurple }
</style>
<script webc:bucket="defer">
	console.log("Hello possum.");
</script>
<footer>Hello possum.</footer>

Filename index.webc

<!DOCTYPE html>
<title>WebC Example</title>
<style @raw="getBundle('css')" webc:keep></style>
<div>
	<my-footer></my-footer>
</div>
<style @raw="getBundle('css', 'defer')" webc:keep></style>
<script @raw="getBundle('js', 'defer')" webc:keep></script>

Output example _site/index.html

<!DOCTYPE html>
<html>
	<head>
		<title>WebC Example</title>
		<style>footer { color: rebeccapurple }</style>
	</head>
	<body>
		<div>
			<my-footer>
				<footer>Hello possum.</footer>
			</my-footer>
		</div>
		<style></style>
		<script>console.log("Hello possum.");</script>
	</body>
</html>

Filename _components/my-footer.webc

<style>
	footer { color: rebeccapurple }
</style>
<script>
	console.log("Hello possum.");
</script>
<footer>Hello possum.</footer>

Filename index.webc

<!DOCTYPE html>
<title>WebC Example</title>
<style @raw="getBundle('css')" webc:keep></style>
<div webc:bucket="defer">
	<my-footer></my-footer>
</div>
<style @raw="getBundle('css', 'defer')" webc:keep></style>
<script @raw="getBundle('js', 'defer')" webc:keep></script>

Output example _site/index.html

<!DOCTYPE html>
<html>
	<head>
		<title>WebC Example</title>
		<style></style>
	</head>
	<body>
		<div>
			<my-footer>
				<footer>Hello possum.</footer>
			</my-footer>
		</div>
		<style>footer { color: rebeccapurple }</style>
		<script>console.log("Hello possum.");</script>
	</body>
</html>

Added to any other element, webc:bucket cascades to every element and component inside it, as in the second example.
The value can be a JavaScript expression with the : prefix, e.g. :webc:bucket="bucketName".

Opting out of WebC processing

`webc:raw`

Skips WebC processing for everything inside the element, so components, @ and : attributes are output as written. Attributes on the element itself are still processed. This works well with the <template> element, which WebC leaves in the output.

Filename _components/my-component.webc

<template webc:raw>
	<story-card @title="Top 10 Fashionable Possums"></story-card>
	<style>
		p { color: rebeccapurple }
	</style>
</template>

Filename index.webc

<my-component></my-component>

Output example _site/index.html

<template>
	<story-card @title="Top 10 Fashionable Possums"></story-card>
	<style>
		p { color: rebeccapurple }
	</style>
</template>

Related: @raw property

`webc:ignore`

Added in @11ty/webc@0.9.0Removes the element and its content from processing and output entirely. This is useful for server-side comments or usage documentation in a component.

Filename _components/story-card.webc

<template webc:ignore>
	Usage:
	<story-card @title="Top 10 Fashionable Possums"></story-card>
</template>
<div class="story-card">
	<h1 @text="title"></h1>
</div>

Filename index.webc

<story-card @title="Top 10 Fashionable Possums"></story-card>

Output example _site/index.html

<div class="story-card">
	<h1>Top 10 Fashionable Possums</h1>
</div>

Server-only comments

Added in @11ty/webc@0.10.0

Add one or more dashes to the start and end of an HTML comment and WebC removes it from the output. A standard HTML comment is rendered to the output as usual.

Filename _components/my-component.webc

<!------- WebC removes this comment ------->
<!--- WebC removes this comment --->
<!-- WebC does NOT remove this comment -->
<p>Hello possum.</p>

Filename index.webc

<my-component></my-component>

Output example _site/index.html

<!-- WebC does NOT remove this comment -->
<p>Hello possum.</p>

Subtleties and limitations

Void elements

Custom elements are not supported as void elements, they require both a starting and ending tag (as per the HTML specification). This means a WebC component cannot be self-closing. To work around this limitation, use webc:is on a void element (e.g. <img webc:is="my-image" src="possum.jpeg">), or name the component file after the void element itself (e.g. _components/img.webc).

Head components

The HTML parser moves custom element children of <head> into the <body>. To work around this limitation, use webc:is on an element that is allowed in <head>, such as <template>.

Filename _components/site-meta.webc

<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">

Filename index.webc

<!DOCTYPE html>
<html lang="en">
	<head>
		<template webc:is="site-meta"></template>
		<title>WebC Example</title>
	</head>
	<body>
		<p>Hello possum.</p>
	</body>
</html>

Output example _site/index.html

<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="utf-8">
		<meta name="viewport" content="width=device-width, initial-scale=1">
		<title>WebC Example</title>
	</head>
	<body>
		<p>Hello possum.</p>
	</body>
</html>

Table components

WebC uses the parse5 library, so it parses and tokenizes every WebC file the same way a web browser does. If you put a <table> element in a custom WebC element and pass its <tr> and <td> elements through a slot, the parser sees the <tr> and <td> elements as orphans. It removes them during the initial parse and places the table internals as siblings of the table.

To work around this limitation, use webc:is for the <table>, <tr>, and <td> elements.

Filename _components/possum-table.webc

<template webc:is="table">
	<slot></slot>
</template>

Filename index.webc

<possum-table>
	<template webc:is="tr">
		<template webc:is="td">Susan</template>
		<template webc:is="td">Is strong</template>
	</template>
</possum-table>

Output example _site/index.html

<table>
	<tr>
		<td>Susan</td>
		<td>Is strong</td>
	</tr>
</table>

Rendering modes

Eleventy has two rendering modes: page and component. WebC chooses the mode from the markup you supply. The page mode renders full HTML pages. The component mode renders fragments of HTML. Most of the time you do not need to think about this distinction, but it is documented here for completeness.

page is used when the markup starts with <!doctype (or <!DOCTYPE) or <html (WebC forces no-quirks parsing).
component is used otherwise.

Differences from HTML parsing

Added in @11ty/webc@0.9.0WebC processes content inside of both <template> and <noscript> elements. The HTML parser treats these as plaintext.

Eleventy + WebC Features

Front Matter

WebC in Eleventy works automatically with standard Eleventy conventions for front matter (though front matter in Eleventy is optional).

Filename with-front-matter.webc

---
layout: "my-layout.webc"
---
WebC *is* HTML.

Expand to see an example my-layout.webc

The above example assumes the existence of _includes/my-layout.webc (an Eleventy layout).

Filename _includes/my-layout.webc

<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="utf-8" />
		<title>WebC Example</title>
	</head>
	<body @raw="content"></body>
</html>

Read more about the WebC properties: @raw Added in @11ty/webc@0.7.1 and @html.

Front matter (per standard Eleventy conventions) is supported in page-level templates only (.webc files in your input directory), not in components.

Defining Components

Components are the magic of WebC and there are a few ways to define components in WebC:

Use global no-import components specified in your config file.
Specify a glob of no-import components at a directory or template level in the data cascade.
You can use webc:import inside of your components to import another component directly.

Notably, WebC components can have any valid HTML tag name! They are not restricted to the same naming limitations as custom elements (which require a dash in the name).

Global no-import Components

Use the components property in the options passed to addPlugin in your Eleventy configuration file to specify project-wide WebC component files available for use in any page.

The components option accepts:

String (file path or glob)
Array (of file paths or globs) Added in @11ty/eleventy-plugin-webc@0.9.2
npm: prefix aliases Added in @11ty/eleventy-plugin-webc@0.9.2

eleventy.config.js

ESM CommonJS

import pluginWebc from "@11ty/eleventy-plugin-webc";

export default function (eleventyConfig) {
	eleventyConfig.addPlugin(pluginWebc, {
		// Glob to find no-import global components
		// This path is relative to the project-root!
		// The default value is shown:
		components: "_components/**/*.webc",

		// or an Array (Eleventy WebC v0.9.2+)
		components: [
			"_components/**/*.webc",
			"npm:@11ty/is-land/*.webc",
			"npm:@11ty/eleventy-plugin-syntaxhighlight/*.webc",
		],
	});
};

const pluginWebc = require("@11ty/eleventy-plugin-webc");

module.exports = function (eleventyConfig) {
	eleventyConfig.addPlugin(pluginWebc, {
		// Glob to find no-import global components
		// This path is relative to the project-root!
		// The default value is shown:
		components: "_components/**/*.webc",

		// or an Array (Eleventy WebC v0.9.2+)
		components: [
			"_components/**/*.webc",
			"npm:@11ty/is-land/*.webc",
			"npm:@11ty/eleventy-plugin-syntaxhighlight/*.webc",
		],
	});
};

The path for components is relative to your project root (not your project’s input directory).

The file names of components found in the glob determine the global tag name used in your project (e.g. _components/my-component.webc will give you access to <my-component>).

Declaring Components in Front Matter

You can also use and configure specific components in front matter (or, via any part of the data cascade—scoped to a folder or a template) by assigning a glob (or array of globs) to the property at webc.components:

Filename my-directory/my-page.webc

---
layout: "my-layout.webc"
webc:
  components: "./webc/*.webc"
---

<my-webc-component>WebC *is* HTML.</my-webc-component>

WARNING

By default these paths are relative to the template file. If you’re setting this in the data cascade in a directory data file that will apply multiple child folders deep, it might be better to:

Use the global no-import components option.
Use ~/ as a prefix (e.g. ~/my-directory/webc/*.webc) to alias to the project’s root directory.

Official WebC Components

The following plugins offer official WebC components for use in your projects:

@11ty/is-land supplies <is-land>
- Example: <is-land webc:import="npm:@11ty/is-land">
- Read more at Use with is-land
@11ty/eleventy-plugin-syntaxhighlight supplies <syntax-highlight>
- Example: <syntax-highlight language="js" webc:import="npm:@11ty/eleventy-plugin-syntaxhighlight">
- Read more at Syntax Highlighting Plugin
@11ty/eleventy-img supplies <eleventy-image>
- Added in Image v3.1.0
- Example: <img webc:is="eleventy-image" webc:import="npm:@11ty/eleventy-img">
- Read more at the Image WebC component.

Eleventy Data Cascade

To access global data from the Data Cascade, use the $data variable in your component’s JavaScript. For example, if you have this in _data/site.json:

{
  "title": "My Site Title"
}

In an internal WebC component, such as one in src/_includes/components/*, you can access that data via:

<h1 @text="$data.site.title"></h1>

In a top-level WebC template, such as a layout file or other *.webc files in the Eleventy input folder, you can access global data variables directly without $data:

<h1 @text="site.title"></h1>

CSS and JS (Bundler mode)

Eleventy WebC bundles each page’s assets (the CSS and JS used by components on the page). WebC rolls these up automatically when a component uses <script>, <script src>, <style>, or <link rel="stylesheet">. You can use this to implement component-driven Critical CSS.

Note on Declarative Shadow DOM: elements inside of declarative shadow root template (<template shadowrootmode> or the deprecated <template shadowroot>) are left as is and not bundled.

Filename _components/my-webc-component.webc

<style>
	/* This is component CSS */
</style>
<script>
	/* This is component JS */
</script>

<!-- Local file references work too -->
<link rel="stylesheet" href="my-file.css" />
<script src="my-file.js"></script>

As shown above this also includes <link rel="stylesheet"> and <script src> when the URLs point to files on the file system (remote URL sources are not yet supported).

You can opt-out of bundling on a per-element basis using webc:keep.

Filename _includes/layout.webc

<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="utf-8" />
		<title>WebC Example</title>

		<!-- inline bundles -->
		<style @raw="getBundle('css')" webc:keep></style>
		<script @raw="getBundle('js')" webc:keep></script>

		<!-- or write your bundle to a file -->
		<link rel="stylesheet" :href="getBundleFileUrl('css')" webc:keep />
		<script :src="getBundleFileUrl('js')" webc:keep></script>
	</head>
	<body @raw="content"></body>
</html>

Added in @11ty/eleventy-plugin-webc@0.9.0Eleventy WebC uses the Bundle Plugin behind the scenes to implement bundling. getBundle('css') and getBundle('js') can now be used instead of getCss(page.url) and getJs(page.url) respectively.
Added in @11ty/webc@0.8.0webc:keep is required on <style> and <script> in your layout files to prevent re-bundling the bundles.
Added in @11ty/webc@0.8.0The getCss and getJs helpers are now available to all WebC templates without restriction. Previous versions required them to be used in an Eleventy Layout file.
@raw was Added in @11ty/webc@0.7.1. Previous versions can use webc:raw @html.

Bundle Code Ordering

The order of the code in these bundles is determined by the dependency order of the components, from most specific to least specific!

Expand to see an example

This example has an index.webc page that uses a header.webc component.

Filename index.webc

<style>
	/* index.webc */
</style>
<header></header>

Filename _components/header.webc

<style>
	/* header.webc */
</style>

The CSS bundle looks like:

/* header.webc */
/* index.webc */

Access Bundles in other Template Engines

You can access these bundles in other templates types too (.njk, .liquid, etc.).

Added in @11ty/eleventy-plugin-webc@0.9.0Eleventy WebC uses the Bundle Plugin behind the scenes to implement bundling. This plugin provides getBundle and getBundleFileUrl universal shortcodes for use in any template type (including WebC as shown above).

WebC v0.8.0 and older: Check out the deprecated (but still in place for backwards compatibility) webcGetCss and webcGetJs universal filters for bundle output.

Filename _includes/layout.njk

<style>{{ page.url | webcGetCss | safe }}</style>
<script>{{ page.url | webcGetJs | safe }}</script>
<!-- write to a file -->
<link rel="stylesheet" href="{% getBundleFileUrl "css" %}">

Filename _includes/layout.liquid

<style>{{ page.url | webcGetCss }}</style>
<script>{{ page.url | webcGetJs }}</script>

Asset bucketing

Bucketing is an additional layer of bundling. webc:bucket sends a component’s CSS or JavaScript to a named bucket instead of the default one.

This component outputs code to two separate buckets:

Filename _components/my-webc-component.webc

<style>
	/* This CSS is put into the default bucket */
</style>
<script>
	/* This JS is put into the default bucket */
</script>
<style webc:bucket="defer">
	/* This CSS is put into the `defer` bucket */
</style>
<script webc:bucket="defer">
	/* This JS is put into the `defer` bucket */
</script>

When <my-webc-component> is used on a page, WebC rolls its assets into the page-specific bucket bundles for CSS and JavaScript.

You can then output those bucket bundles anywhere on your page, as in this Eleventy layout file:

Filename _includes/layout.webc

<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="utf-8" />
		<title>WebC Example</title>
		<!-- Default bucket -->
		<style @raw="getBundle('css')" webc:keep></style>
		<script @raw="getBundle('js')" webc:keep></script>
	</head>
	<body>
		<template @raw="content" webc:nokeep></template>

		<!-- `defer` bucket -->
		<style @raw="getBundle('css', 'defer')" webc:keep></style>
		<script @raw="getBundle('js', 'defer')" webc:keep></script>
	</body>
</html>

Added in @11ty/webc@0.8.0webc:keep is required on <style> and <script> in your layout files to prevent re-bundling the bundles.
Added in @11ty/webc@0.9.1:webc:bucket (dynamic attribute) is supported to set this value via JavaScript. #120

Cascading Asset Buckets

Added in @11ty/webc@0.9.1 Additionally, webc:bucket can be added to any tag and cascades to all child content.

Consider this WebC page:

Filename index.webc

<!-- has an implied webc:bucket="default" -->
<my-component></my-component>

<div webc:bucket="defer">
	<!-- each of these have webc:bucket="defer" -->
	<!-- (including any nested components inside, too) -->
	<footnote-references></footnote-references>

	<my-footer></my-footer>
</div>

Setting webc:bucket cascades to all of the children as if each had webc:bucket="defer" assigned individually. All assets used in those components are rolled up into the defer bucket.

Conflicts and hoisting

What happens when a component is used in multiple distinct buckets?

Filename index.webc

<!-- has an implied webc:bucket="default" -->
<my-component></my-component>

<div webc:bucket="defer">
	<my-component></my-component>
</div>

When duplicates and conflicts occur, WebC hoists the component code to the nearest shared bucket for you. In this example, the CSS and JS for <my-component> are loaded in the default bucket and only in the default bucket.

Use with `is-land`

You can also use this out of the box with Eleventy’s is-land component for web component hydration.

At the component level, components can declare their own is-land loading conditions.

Filename index.webc

<is-land on:visible webc:import="npm:@11ty/is-land">
	<template data-island>
		<!-- CSS -->
		<style webc:keep>
			/* This CSS applies on:visible */
		</style>
		<link rel="stylesheet" href="arbitrary.css" webc:keep />

		<!-- JS -->
		<script type="module" webc:keep>
			console.log("This JavaScript runs on:visible");
		</script>
		<script type="module" src="arbitrary.js" webc:keep></script>
	</template>
</is-land>

From the Community

×58 resources via 11tybundle.dev curated by Bob Monsour.

Eleventy — Tom MacWright (2026)
Recently Played: bringing back my Last.fm component — Martin Hicks (2026)
Using 11ty's WebC to separate web components out into separate files — Stuart Langridge (2026)
WebC Quirks — Harris Lapiroff (2025)
We migrated our site to Eleventy and increased performance by 24% — Dan Webb (2025)

Expand to see 53 more resources.

Switching to WebC — Harris Lapiroff (2025)
How My Terminal Text WebC Component Works_ — John Michael Swartz (2025)
Building a resume website with eleventy — Keith Kurson (2025)
This blog's comments are powered by Webmentions — Matt Steele (2025)
11ty WebC If Statements and Attributes — Keith Wagner (2024)
From Gatsby to Eleventy — Matt Steele (2024)
I rebuilt my website from scratch with WebC — Fynn Becker (2024)
Oddbird’s Winging It Live: Web Components — Zach Leatherman (2024)
WebC at scale — Ben White (2024)
Eleventy Buckets & Cascade Layers — Miriam Suzanne (2024)
Nested pagination with 11ty — Ben White (2024)
Building with Eleventy — Keith Kurson (2024)
Unveiling the Marvels of 11ty's WebC — Ryan Gittings (2024)
Elevating Video Transcripts as Searchable Content — Zach Leatherman (2024)
The Good, the Bad, the Web Components — Zach Leatherman (2024)
Migrating my site from NextJS to Eleventy — Sandro Roth (2023)
Eleventy WebC in a nutshell — Rob Anderson (2023)
Automating Eleventy Server with Visual Studio Code Tasks — Dan Ryan (2023)
WebC is neat! with Zach Leatherman, Web Developer — Nick Taylor (2023)
Under the hood — Horacio Gonzalez (2023)
Eleventy components woes — Tomek Poniatowicz (2023)
webc.nvim — Benny Powers (2023)
Supercharge your HTML with WebC — David Luhr (2023)
Eleventy Style Guide Generator with WebC Component Support — Steven Woodson (2023)
WebC Declarative Shadow DOM Slot Workarounds — Benny Powers (2023)
Creating Bootstrap WebC Components in Eleventy — Raymond Camden (2023)
Extending 11ty’s page variable — Adam Stoddard (2023)
WebC First Impressions — Benny Powers (2023)
webc-starter-kit (Github repo) — Mathieu Huot (2023)
A WebC-focused YouTube playlist — Ricky de Laveaga (2023)
3 Methods for scoped styles in web components that work everywhere — Zach Leatherman (2023)
WebC Updates in Eleventy - Looping — Raymond Camden (2023)
WebC Updates in Eleventy — Raymond Camden (2023)
Rewriting the Eleventy Home Page in WebC — Zach Leatherman (2023)
Using WebC for progressively-enhanced UI elements — Lewis Dale (2023)
Using Eleventy and WebC for Simpler, Performant Web Components - YouTube — Raymond Camden (2023)
WebC for 11ty — Rob Wood (2023)
Using JavaScript in a WebC Component — Raymond Camden (2023)
Quick WebC Tip — Raymond Camden (2023)
Quick Tip for Eleventy's WebC support — Raymond Camden (2023)
Importing external components in WebC via NPM — Ashur Cabrera (2022)
Eleventy 2.0 & WebC — Martin Hicks (2022)
Exploring WebC — Constant Vallee (2022)
Building a YouTube Embed Web Component (both vanilla and WebC flavored) — Raymond Camden (2022)
My notes on Eleventy WebC components — Levi McGranahan (2022)
Understanding WebC Features and Concepts — Stephanie Eckles (2022)
WebC — Fuzzy Logic (2022)
The WebC Episode with a Bonus Server-Rendered Image Comparison Component on Eleventy — Zach Leatherman (2022)
First Experience Building with Eleventy's WebC Plugin — Raymond Camden (2022)
Introduction to WebC — Stephanie Eckles (2022)
Interactive Progressively-enhanced Web Components with WebC — Zach Leatherman (2022)
Crash Course in Eleventy's new WebC Plugin — Zach Leatherman (2022)
Using Storybook With 11ty — Paul Everitt (2022)

RSS

2026-08-27T17:37:59Z

RSS Plugin

On this page

A pack of plugins for generating an RSS (or Atom or JSON) feed using the Nunjucks templating syntax.

GitHub.

Feature highlights

URLs are normalized to absolute URLs, pointing to your hosted domain for maximum feed reader compatibility. Read more about the dangers of relative URLs in your feeds on CSS Tricks (Related: #36).
Existing project Transforms are applied to feed entries (e.g. Image HTML Transform, <base>, InputPath to URL, etc.) If you’re using a --pathprefix in your project, the URLs in your feed content are normalized for you.

Since RSS Plugin v2.0, this plugin offers two options to create feeds in your project:

Virtual templates let you create a feed with a few lines of configuration. (This is easier, more abstracted.)
Manual templates need more configuration and a template file. (This requires more setup, but offers more control.)

Installation

Available on npm.

npm install @11ty/eleventy-plugin-rss

v2 of this plugin requires Eleventy v3.0 or newer.
v1 of this plugin is compatible with Eleventy 0.11 or newer.

Virtual Template

Added in v3.0.0Added in RSS 2.0.0 This method creates a feed template directly from your plugin configuration, without requiring additional files in your project. The default template uses Nunjucks, so make sure njk is included templateFormats in your Eleventy config. Read more about Virtual Templates.

Added in RSS 3.0.0Version 3 of this plugin is now using ESM. This requires Eleventy v3 or newer. Additionally, if you’re using a CommonJS configuration file and an older version of Node (< 20.19), you’ll need to use dynamic import() instead of require.

eleventy.config.js

ESM CommonJS

import { feedPlugin } from "@11ty/eleventy-plugin-rss";

export default function (eleventyConfig) {
	eleventyConfig.addPlugin(feedPlugin, {
		type: "atom", // or "rss", "json"
		outputPath: "/feed.xml",
		collection: {
			name: "posts", // iterate over `collections.posts`
			limit: 10,     // 0 means no limit
		},
		metadata: {
			language: "en",
			title: "Blog Title",
			subtitle: "This is a longer description about your blog.",
			base: "https://example.com/",
			author: {
				name: "Your Name",
				email: "", // Optional
			}
		}
	});
};

const { feedPlugin } = require("@11ty/eleventy-plugin-rss");

module.exports = function (eleventyConfig) {
	eleventyConfig.addPlugin(feedPlugin, {
		type: "atom", // or "rss", "json"
		outputPath: "/feed.xml",
		collection: {
			name: "posts", // iterate over `collections.posts`
			limit: 10,     // 0 means no limit
		},
		metadata: {
			language: "en",
			title: "Blog Title",
			subtitle: "This is a longer description about your blog.",
			base: "https://example.com/",
			author: {
				name: "Your Name",
				email: "", // Optional
			}
		}
	});
};

This configuration is the only step for the Virtual Template method. If you need additional control over the template output, you can use the Manual Template method.

Expand for full options list

type: (required) One of "atom" (default), "rss", or "json"
outputPath: (required, default: /feed.xml) Where to write the template in the output directory.
inputPath: (optional, default based on metadata.title) Change where the virtual template pretends to live on the file system (e.g. if you want project directory data files to apply via the Data Cascade)
collection.name: Collection entries to iterate over to populate your feed (e.g. name: "posts" for collections.posts)
collection.limit: Number of entries to include. (Use 0 for no limit.)
metadata: Content used to populate the feed boilerplate.
stylesheet: URL to an XSL stylesheet to change how the feed is rendered in the browser (only for Atom and RSS feeds).
templateData, defaults to {}: Additional data to apply to the template (e.g. to add your feed to the Navigation plugin)

Manual Template

Configuration

Open up your Eleventy config file (probably eleventy.config.js) and use addPlugin:

eleventy.config.js

ESM CommonJS

import pluginRss from "@11ty/eleventy-plugin-rss";

export default function (eleventyConfig) {
	eleventyConfig.addPlugin(pluginRss);
};

const pluginRss = require("@11ty/eleventy-plugin-rss");

module.exports = function (eleventyConfig) {
	eleventyConfig.addPlugin(pluginRss);
};

Expand to see full options list

Added in RSS 1.1.0 Advanced control of PostHTML rendering options via posthtmlRenderOptions.

eleventy.config.js

ESM CommonJS

import pluginRss from "@11ty/eleventy-plugin-rss";

export default function (eleventyConfig) {
	eleventyConfig.addPlugin(pluginRss, {
		posthtmlRenderOptions: {
			closingSingleTag: "default", // opt-out of <img/>-style XHTML single tags
		},
	});
};

const pluginRss = require("@11ty/eleventy-plugin-rss");

module.exports = function (eleventyConfig) {
	eleventyConfig.addPlugin(pluginRss, {
		posthtmlRenderOptions: {
			closingSingleTag: "default", // opt-out of <img/>-style XHTML single tags
		},
	});
};

Supplies the following Nunjucks Filters

getNewestCollectionItemDate: Gets the most recently updated content in the collection. Use with dateToRfc3339 to properly format the Date for the top-level <updated> element. Added in RSS 1.1.0
dateToRfc3339: format a Date for use in a <entry><updated> element. (Atom feeds) Added in RSS 1.1.0
dateToRfc822: format a Date for use in a <pubDate> element. (RSS feeds) Added in RSS 1.2.0

Less Important Filters

Deprecated absoluteUrl: For performance reasons, the renderTransforms filter is recommended instead, making use of the HTML <base> plugin. Converts a single URL (relative or absolute path) to a full absolute URL including protocol, domain, full path.
Deprecated htmlToAbsoluteUrls: For performance reasons, the renderTransforms filter is recommended instead, making use of the HTML <base> plugin. (async) Transforms all of the URLs in a block of HTML with absoluteUrl above. Uses posthtml-urls with a[href], video[src], audio[src], source, img[src], [srcset] and a whole bunch more.
⚠️ Removed in RSS v2.0.0 rssLastUpdatedDate, poorly named (works with Atom and JSON feeds, not RSS). Use getNewestCollectionItemDate | dateToRfc3339 instead.
⚠️ Removed in RSS v2.0.0 rssDate, poorly named (works with Atom and JSON feeds, not RSS). Use dateToRfc3339 instead.

Use with other template languages

Added in RSS 1.1.0 This plugin exports dateToRfc3339, dateToRfc822 (Added in RSS 1.2.0), getNewestCollectionItemDate, absoluteUrl, and convertHtmlToAbsoluteUrls functions so you can use with your own filters. For example:

eleventy.config.js

ESM CommonJS

import pluginRss from "@11ty/eleventy-plugin-rss";

export default function (eleventyConfig) {
	eleventyConfig.addLiquidFilter("dateToRfc3339", pluginRss.dateToRfc3339);

	// New in RSS 1.2.0
	eleventyConfig.addLiquidFilter("dateToRfc822", pluginRss.dateToRfc822);
};

const pluginRss = require("@11ty/eleventy-plugin-rss");

module.exports = function (eleventyConfig) {
	eleventyConfig.addLiquidFilter("dateToRfc3339", pluginRss.dateToRfc3339);

	// New in RSS 1.2.0
	eleventyConfig.addLiquidFilter("dateToRfc822", pluginRss.dateToRfc822);
};

Do keep in mind that escaping HTML content is a feature provided as part of Nunjucks. Moving to another template language may require a different option for escaping (for example, html-entities).

Sample Feed templates

Copy and paste this template and modify the JSON metadata to match your feed’s needs. Make sure collections.posts matches the template collection you want to provide a feed for.

The following feed samples require RSS Plugin v2.0 or newer. Samples for RSS Plugin v1 are available on older versions of the docs.

Atom RSS JSON

---json
{
  "permalink": "feed.xml",
  "eleventyExcludeFromCollections": true,
  "metadata": {
    "title": "My Blog about Boats",
    "description": "I am writing about my experiences as a naval navel-gazer.",
    "language": "en",
    "base": "https://example.com/",
    "author": {
      "name": "Boaty McBoatFace"
    }
  }
}
---
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="{{ metadata.language or page.lang }}">
  <title>{{ metadata.title }}</title>
  <subtitle>{{ metadata.description }}</subtitle>
  <link href="{{ permalink | htmlBaseUrl(metadata.base) }}" rel="self" />
  <link href="{{ metadata.base | addPathPrefixToFullUrl }}" />
  <updated>{{ collections.posts | getNewestCollectionItemDate | dateToRfc3339 }}</updated>
  <id>{{ metadata.base | addPathPrefixToFullUrl }}</id>
  <author>
    <name>{{ metadata.author.name }}</name>
  </author>
  {%- for post in collections.posts | reverse %}
  {%- set absolutePostUrl %}{{ post.url | htmlBaseUrl(metadata.base) }}{% endset %}
  <entry>
    <title>{{ post.data.title }}</title>
    <link href="{{ absolutePostUrl }}" />
    <updated>{{ post.date | dateToRfc3339 }}</updated>
    <id>{{ absolutePostUrl }}</id>
    <content type="html">{{ post.content | renderTransforms(post.data.page, metadata.base) }}</content>
  </entry>
  {%- endfor %}
</feed>

---json
{
  "permalink": "feed.xml",
  "eleventyExcludeFromCollections": true,
  "metadata": {
    "title": "My Blog about Boats",
    "description": "I am writing about my experiences as a naval navel-gazer.",
    "language": "en",
    "base": "https://example.com/",
    "author": {
      "name": "Boaty McBoatFace"
    }
  }
}
---
<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0" xmlns:dc="http://purl.org/dc/elements/1.1/" xml:base="{{ metadata.base | addPathPrefixToFullUrl }}" xmlns:atom="http://www.w3.org/2005/Atom">
  <channel>
    <title>{{ metadata.title }}</title>
    <link>{{ metadata.base | addPathPrefixToFullUrl }}</link>
    <atom:link href="{{ permalink | htmlBaseUrl(metadata.base) }}" rel="self" type="application/rss+xml" />
    <description>{{ metadata.description }}</description>
    <language>{{ metadata.language or page.lang }}</language>
    {%- for post in collections.posts | reverse %}
    {%- set absolutePostUrl = post.url | htmlBaseUrl(metadata.base) %}
    <item>
      <title>{{ post.data.title }}</title>
      <link>{{ absolutePostUrl }}</link>
      <description>{{ post.content | renderTransforms(post.data.page, metadata.base) }}</description>
      <pubDate>{{ post.date | dateToRfc822 }}</pubDate>
      <dc:creator>{{ metadata.author.name }}</dc:creator>
      <guid>{{ absolutePostUrl }}</guid>
    </item>
    {%- endfor %}
  </channel>
</rss>

---json
{
  "permalink": "feed.json",
  "eleventyExcludeFromCollections": true,
  "metadata": {
    "title": "My Blog about Boats",
    "description": "I am writing about my experiences as a naval navel-gazer.",
    "language": "en",
    "base": "https://example.com/",
    "author": {
      "name": "Boaty McBoatFace"
    }
  }
}
---
{
  "version": "https://jsonfeed.org/version/1.1",
  "title": "{{ metadata.title }}",
  "language": "{{ metadata.language or page.lang }}",
  "home_page_url": "{{ metadata.base | addPathPrefixToFullUrl }}",
  "feed_url": "{{ permalink | htmlBaseUrl(metadata.base) }}",
  "description": "{{ metadata.description }}",
  "authors": [
    {
      "name": "{{ metadata.author.name }}"
    }
  ],
  "items": [
    {%- for post in collections.posts | reverse %}
    {%- set absolutePostUrl %}{{ post.url | htmlBaseUrl(metadata.base) }}{% endset %}
    {
      "id": "{{ absolutePostUrl }}",
      "url": "{{ absolutePostUrl }}",
      "title": "{{ post.data.title }}",
      "content_html": {% if post.content %}{{ post.content | renderTransforms(post.data.page, metadata.base) | dump | safe }}{% else %}""{% endif %},
      "date_published": "{{ post.date | dateToRfc3339 }}"
    }
    {% if not loop.last %},{% endif %}
    {%- endfor %}
  ]
}

Place the file in your input directory, and give it a .njk extension. (For example: src/feed.njk or src/feed.json.) If your input directory is src, the file will be transformed into a feed.xml (or feed.json if you’re using the JSON variant) file at the root of your website when Eleventy builds. It can then be useful to check the file against a feed validator, such as the W3C Feed Validation Service to make sure that the output was good.

Ultimately, your feed will be available at https://yourwebsite.com/feed.xml (or https://yourwebsite.com/feed.json).

Community Plugins

eleventy-xml-plugin for Liquid.

Glossary

2026-08-27T17:37:59Z

Glossary

This page provides two lists of terms — one for Eleventy-specific terminology that may be useful for when building out a project using Eleventy, and one for industry jargon that may be useful for understanding context.

Work in progress: Edit this page

Eleventy-Specific Terminology

Template

A content file written in a format such as Markdown, HTML, Liquid, Nunjucks, and more, which Eleventy transforms into a page (or pages) in the built site. Templates can access data exposed through the data cascade with templating syntax.

Layout

A template which wraps around another template, typically to provide the scaffolding markup for content to sit in.

Data

Exposed via variables that can be used inside templates and layouts using templating syntax. The data for a given template is aggregated through a process called the data cascade.

Data Cascade

Eleventy's order of operations for evaluating all data for any given template, and for resolving conflicts that arise. The data cascade follows the principle of colocation, so data defined broadly to apply to many templates will be overruled by data that targets the given template more specifically.

Filter

A function which can be used within templating syntax to transform data into a more presentable format. Filters are typically designed to be chained, so that the value returned from one filter is piped into the next filter.

Shortcode

A function which can be used within templating syntax to inject content into templates. Shortcodes can take many arguments, and can be thought of as a templating approach to reusable markup.

Collection

An array of templates, used to group similar content. Collections can be created by using tags or by calling the collections API in the Eleventy configuration.

Pagination

A way to create pages by iterating over data. The same template is applied to each chunk of the paginated data.

Plugin

A portable, installable Eleventy configuration which can add data, filters, shortcodes, and more to a project's setup.

Industry Terms and Buzzwords

Bask in the warm glow of this “Nobody ever got fired for buying IBM”-style feel-good industry jargon.

Our industry can be particularly bad about inventing words for things that already exist. Hopefully this page will help you navigate the labyrinth.

Static Sites

A static site is a group of generated HTML files. Content is built into the HTML files rather than using a dynamic back end language to generate the content on-the-fly. A dynamic site can appear static when you add caching rules to make the content stickier. A static site can appear dynamic when you run your build quickly and often.

Jamstack

Modern web development architecture based on client-side JavaScript, reusable APIs, and prebuilt Markup.—jamstack.org

Eleventy facilitates Jamstack sites—but you maintain full control over the JavaScript.

Progressive Enhancement

The idea that content should be the priority for a website's development. In other words, start with only essential content and functionality that works with as many users as possible, and then progressively enhance from there.

As stated in the MDN Web Docs: "Special notice should be taken of accessibility. Acceptable alternatives should be provided where possible."

Data-Driven

Make components and markup data-driven so that you don’t have a bunch of one-off copy-pasted HTML instances littered throughout your project.

Serverless Friendly

“You can take your front-end skills and do things that typically only a back-end can do. You can write a JavaScript function that you run and receive a response from by hitting a URL.”—The Power of Serverless from Chris Coyier

Take care to make sure that serverless functions are progressively enhanced. If you call serverless functions in client-side JavaScript, they should be used for features that are outside the core functionality of the site.

Lean Web

To be honest it’s kind of a stretch to relate Lean methodology to this project but the term just kinda feels right.

Zero Config

Zero config means that Eleventy can run without any command line parameters or configuration files.

We’ve taken care to setup Eleventy so that running the stock eleventy command uses sensible defaults. Lower the barrier to entry for that first project build to get up and running faster.

Convention over Configuration Routing

Can you believe that some frameworks require a centralized piece of configuration for routing? eleventy routes map the file system, unless you override with a permalink.

Pre-rendered Templates by Default

With the rise of client side rendering of templates in JavaScript came significant performance problems, especially with users of less-capable (but none-the-less still modern) hardware. Did you know they’re selling new mobile devices that are pretty hardware-limited?

Many frameworks switched to Server Side Rendering, which meant running an application server with middleware that would render the markup on demand for each request. Eleventy templates by default are generated (some call this pre-rendering) at build time for maximum performance. This way the web server only needs to fetch the static file and send it back to the user.

Hydration-less

Well, uh, we don’t inject or use any client-side JavaScript in Eleventy, so there’s nothing that needs hydration.

Apps not App Servers

Application servers can be slow. Instead of PHP, Java, or even Node.js dynamically generating page responses on the fly when the request comes in, have your pre-rendered templates ready to go for delivery! Maximum performance.

Single Page Applications (SPA) versus Multi-Page Applications (MPA)

Single Page Applications (SPA) use JavaScript to enable navigations between pages on a web site. Multi-Page Applications use the classic navigation model of the web and do a full page refresh to a new page.

Should you build a Single Page Application with Eleventy?

Where did the Name Come From?

Some might think that the name Eleventy is an homage to Spinal Tap (turn it up to eleven) or more directly, Lord of the Rings. I chose it because of a story my grandma Nonnie loved to tell about how I learned to count. Rather than move from ten to eleven like a normal child, I felt it appropriate to use the teen suffix for the numbers eleven and twelve, counting “ten, eleventy-teen, twelvety-teen, thirteen, …” I always liked that story and it seemed as appropriate a reason as any.—via zachleat.com

What’s the difference between 11ty and Eleventy?

The 11ty name refers to the over-arching organization and community. Eleventy refers to the static site generator specifically. —via Issue #1283

Watch and Serve

2026-08-24T19:50:14Z

Watch Files and use Development Servers

On this page

Running Eleventy with --serve starts a hot reloading local development server for you.

A development server is optional! Using --watch will run Eleventy (and re-run when you save your files) without a server.

Eleventy Dev Server Added in v2.0.0

Eleventy bundles its own dedicated Development Server. In versions prior to v2, we used Browsersync, which you can still use with Eleventy if you’d like.

For most use cases, the default behavior of this server should handle most things automatically. Changing files in your local environment will re-run an Eleventy build and refresh any active web browser sessions on the local site.

Add Your Own Watch Targets

The addWatchTarget config method allows you to manually add a file or directory for Eleventy to watch. When the file or the files in this directory change Eleventy will trigger a build. This is useful if Eleventy is not aware of your project-specific external dependencies.

eleventy.config.js

ESM CommonJS

export default function(eleventyConfig) {
	eleventyConfig.addWatchTarget("./src/scss/");
};

module.exports = function(eleventyConfig) {
	eleventyConfig.addWatchTarget("./src/scss/");
};

Advanced usage note: This works with chokidar under the hood and chokidar uses picomatch for globbing:

Both **/*.(png|jpeg) and **/*.{png,jpeg} are valid globs to matches any png or jpeg file in your project.

Reset configuration Added in v3.0.0

We do automatically look for dependencies in your configuration file based on JavaScript require or import—watch targets not included in that dependency graph will not reset or re-run your configuration automatically.

To reset your configuration for a specific watch target, use the resetConfig option.

eleventy.config.js

ESM CommonJS

export default function(eleventyConfig) {
	// You probably don’t need this
	eleventyConfig.addWatchTarget("./_config/**", {
		resetConfig: true
	});
};

module.exports = function(eleventyConfig) {
	// You probably don’t need this
	eleventyConfig.addWatchTarget("./_config/**", {
		resetConfig: true
	});
};

Reload without running a build

Use the watch option configurable with Eleventy Dev Server to refresh your local browser when local files change without triggering an Eleventy build. This is useful to decouple build processes outside of Eleventy.

Ignore Watching Files

`.gitignore`

Eleventy will ignore changes to files or folders listed in your .gitignore file by default, unless setUseGitIgnore is turned off.

Configuration API Added in v2.0.0

Previously, the configuration API ignores for template processing were also used as ignores for watching (e.g. eleventyConfig.ignores.add("README.md")).

New in v2.0.0, watch target ignores now have their own dedicated API:

eleventy.config.js

ESM CommonJS

export default function(eleventyConfig) {
	// Do not rebuild when README.md changes (You can use a glob here too)
	eleventyConfig.watchIgnores.add("README.md");

	// Or delete entries too
	eleventyConfig.watchIgnores.delete("README.md");
};

module.exports = function(eleventyConfig) {
	// Do not rebuild when README.md changes (You can use a glob here too)
	eleventyConfig.watchIgnores.add("README.md");

	// Or delete entries too
	eleventyConfig.watchIgnores.delete("README.md");
};

The watchIgnores Set starts with a default **/node_modules/** entry.

Watch JavaScript Dependencies

When in --watch mode, Eleventy will spider the dependencies of your JavaScript Templates (.11ty.js), JavaScript Data Files (.11tydata.js or _data/**/*.js), or Configuration File (usually eleventy.config.js) to watch those files too. Files in node_modules directories are ignored. This feature is enabled by default.

eleventy.config.js

ESM CommonJS

export default function(eleventyConfig) {
	// Enabled by default
	eleventyConfig.setWatchJavaScriptDependencies(false);
};

module.exports = function(eleventyConfig) {
	// Enabled by default
	eleventyConfig.setWatchJavaScriptDependencies(false);
};

Add delay before re-running

A hardcoded amount of time Eleventy will wait before triggering a new build when files have changes during --watch or --serve modes. You probably won’t need this, but is useful in some edge cases with other task runners (Gulp, Grunt, etc).

eleventy.config.js

ESM CommonJS

export default function(eleventyConfig) {
	// default is 0
	eleventyConfig.setWatchThrottleWaitTime(100); // in milliseconds
};

module.exports = function(eleventyConfig) {
	// default is 0
	eleventyConfig.setWatchThrottleWaitTime(100); // in milliseconds
};

Advanced `chokidar` Configuration

Advanced chokidar options can be defined using the setChokidarConfig configuration API method:

eleventy.config.js

ESM CommonJS

export default function(eleventyConfig) {
	eleventyConfig.setChokidarConfig({
		usePolling: true,
		interval: 500,
	});
};

module.exports = function(eleventyConfig) {
	eleventyConfig.setChokidarConfig({
		usePolling: true,
		interval: 500,
	});
};

WARNING

If you’re using Windows Subsystem for Linux (WSL) and your project exists outside of your home directory (~), you will likely want to use the usePolling feature to ensure watching works correctly. This is a WSL limitation.

Virtual Templates

2026-08-24T19:50:14Z

Virtual Templates Added in v3.0.0

In addition to template files in your input directory, Eleventy can also process virtual templates defined in your configuration file (or plugins). Related GitHub #1612.

The RSS plugin offers a virtual template to add feeds to your project.

API

eleventyConfig.addTemplate(virtualPath, content, data = {});

virtualPath: used to determine the template language and data cascade for this template. This path is relative to your project’s input directory.
content: usually a string, but maybe JavaScript (if using an 11ty.js template). Can include front matter if the template language supports it.
data: a data object tied to the template. A little more ergonomic than front matter but functionally the same.

Example

Markdown, HTML (via Liquid) Layout

eleventy.config.js

ESM CommonJS

export default function(eleventyConfig) {
	// Create content templates Files
	eleventyConfig.addTemplate("virtual.md", `# Hello`, {
        	layout: "virtual.html"
	});

	// Works great with Layouts too
	eleventyConfig.addTemplate("_includes/virtual.html", `<!-- Layout -->{{ content }}`);
};

module.exports = function(eleventyConfig) {
	// Create content templates Files
	eleventyConfig.addTemplate("virtual.md", `# Hello`, {
        	layout: "virtual.html"
	});

	// Works great with Layouts too
	eleventyConfig.addTemplate("_includes/virtual.html", `<!-- Layout -->{{ content }}`);
};

JavaScript

Any of the JavaScript shapes on 11ty.js templates are also supported here.

eleventy.config.js

ESM CommonJS

export default function(eleventyConfig) {
	// Create content templates Files
	eleventyConfig.addTemplate("virtual.11ty.js", function(data) {
		return `<h1>Hello</h1>`;
	});
};

module.exports = function(eleventyConfig) {
	// Create content templates Files
	eleventyConfig.addTemplate("virtual.11ty.js", function(data) {
		return `<h1>Hello</h1>`;
	});
};

Release History

2026-08-24T19:50:14Z

Release History

You can also browse the latest releases on:

Major Branches

build.awesome.me for v4 (Currently in alpha)
www.11ty.dev for v3 (Latest Stable)
v2.11ty.dev
v1.11ty.dev
v0.11ty.dev

Full Release History

×226 releases total since November 26, 2017

Version	Docs	Date	More…
`v4.0.0-alpha.10` Prerelease		2026 Jul 01	GitHub Release
`v4.0.0-alpha.9` Prerelease		2026 Jul 01	GitHub Release
`v4.0.0-alpha.8` Prerelease		2026 Jun 18	GitHub Release
`v4.0.0-alpha.7` Prerelease		2026 Mar 20	GitHub Release
`v4.0.0-alpha.6` Prerelease		2025 Dec 11	GitHub Release
`v4.0.0-alpha.5` Prerelease		2025 Dec 05	GitHub Release
`v4.0.0-alpha.4` Prerelease		2025 Aug 01	GitHub Release
`v4.0.0-alpha.3` Prerelease		2025 Jul 30	GitHub Release
`v4.0.0-alpha.2` Prerelease		2025 Jul 30	GitHub Release
`v4.0.0-alpha.1` Prerelease		2025 Jul 30	GitHub Release
`v3.1.6`	Docs	2026 Jun 02	GitHub Release
`v3.1.5`	Docs	2026 Mar 18	GitHub Release
`v3.1.4`	Docs	2026 Mar 18	GitHub Release
`v3.1.3`	Docs	2026 Mar 18	GitHub Release
`v3.1.2`	Docs	2025 Jun 24	GitHub Release
`v3.1.2-beta.4` Prerelease		2025 Jun 23	GitHub Release
`v3.1.2-beta.3` Prerelease		2025 Jun 20	GitHub Release
`v3.1.2-beta.2` Prerelease		2025 Jun 18	GitHub Release
`v3.1.2-beta.1` Prerelease		2025 Jun 16	GitHub Release
`v3.1.1`	Docs	2025 Jun 03	GitHub Release
`v3.1.1-beta.3` Prerelease		2025 May 31	GitHub Release
`v3.1.1-beta.2` Prerelease		2025 May 31	GitHub Release
`v3.1.1-beta.1` Prerelease		2025 May 30	GitHub Release
`v3.1.0`	Docs	2025 May 13	GitHub Release
`v3.1.0-beta.1` Prerelease		2025 Apr 18	GitHub Release
`v3.1.0-alpha.1` Prerelease		2025 Apr 14	GitHub Release
`v3.0.1-alpha.5` Prerelease		2025 Mar 14	GitHub Release
`v3.0.1-alpha.4` Prerelease		2025 Jan 29	GitHub Release
`v3.0.1-alpha.3` Prerelease		2025 Jan 14	GitHub Release
`v3.0.1-alpha.2` Prerelease		2025 Jan 14	GitHub Release
`v3.0.1-alpha.1` Prerelease		2024 Dec 20	GitHub Release
`v3.0.0`	Docs	2024 Oct 01	GitHub Release
`v3.0.0-beta.2` Prerelease		2024 Sep 30	GitHub Release
`v3.0.0-beta.1` Prerelease		2024 Jul 31	GitHub Release
`v3.0.0-alpha.20` Prerelease		2024 Sep 11	GitHub Release
`v3.0.0-alpha.19` Prerelease		2024 Sep 04	GitHub Release
`v3.0.0-alpha.18` Prerelease		2024 Jul 30	GitHub Release
`v3.0.0-alpha.17` Prerelease		2024 Jul 16	GitHub Release
`v3.0.0-alpha.16` Prerelease		2024 Jul 09	GitHub Release
`v3.0.0-alpha.15` Prerelease		2024 Jul 09	GitHub Release
`v3.0.0-alpha.14` Prerelease		2024 Jun 27	GitHub Release
`v3.0.0-alpha.13` Prerelease		2024 Jun 12	GitHub Release
`v3.0.0-alpha.12` Prerelease		2024 Jun 11	GitHub Release
`v3.0.0-alpha.11` Prerelease		2024 Jun 10	GitHub Release
`v3.0.0-alpha.10` Prerelease			GitHub Tag
`v3.0.0-alpha.9` Prerelease			GitHub Tag
`v3.0.0-alpha.7` Prerelease			GitHub Tag
`v3.0.0-alpha.5` Prerelease			GitHub Tag
`v3.0.0-alpha.4` Prerelease			GitHub Tag
`v3.0.0-alpha.3` Prerelease			GitHub Tag
`v3.0.0-alpha.2` Prerelease			GitHub Tag
`v3.0.0-alpha.1` Prerelease			GitHub Tag
`v2.0.2-alpha.2` Prerelease			GitHub Tag
`v2.0.2-alpha.1` Prerelease			GitHub Tag
`v2.0.1`	Docs	2023 Mar 28	GitHub Release
`v2.0.1-beta.2` Prerelease			GitHub Tag
`v2.0.1-beta.1` Prerelease			GitHub Tag
`v2.0.1-alpha.3` Prerelease			GitHub Tag
`v2.0.1-alpha.2` Prerelease			GitHub Tag
`v2.0.1-alpha.1` Prerelease			GitHub Tag
`v2.0.0`	Docs	2023 Feb 08	GitHub Release
`v2.0.0-canary.35` Prerelease			GitHub Tag
`v2.0.0-canary.34` Prerelease			GitHub Tag
`v2.0.0-canary.33` Prerelease			GitHub Tag
`v2.0.0-canary.32` Prerelease			GitHub Tag
`v2.0.0-canary.31` Prerelease			GitHub Tag
`v2.0.0-canary.30` Prerelease			GitHub Tag
`v2.0.0-canary.29` Prerelease			GitHub Tag
`v2.0.0-canary.28` Prerelease			GitHub Tag
`v2.0.0-canary.27` Prerelease			GitHub Tag
`v2.0.0-canary.26` Prerelease			GitHub Tag
`v2.0.0-canary.25` Prerelease			GitHub Tag
`v2.0.0-canary.24` Prerelease			GitHub Tag
`v2.0.0-canary.23` Prerelease			GitHub Tag
`v2.0.0-canary.22` Prerelease			GitHub Tag
`v2.0.0-canary.21` Prerelease			GitHub Tag
`v2.0.0-canary.20` Prerelease			GitHub Tag
`v2.0.0-canary.19` Prerelease			GitHub Tag
`v2.0.0-canary.18` Prerelease			GitHub Tag
`v2.0.0-canary.17` Prerelease			GitHub Tag
`v2.0.0-canary.15` Prerelease			GitHub Tag
`v2.0.0-canary.14` Prerelease			GitHub Tag
`v2.0.0-canary.13` Prerelease			GitHub Tag
`v2.0.0-canary.12` Prerelease			GitHub Tag
`v2.0.0-canary.11` Prerelease			GitHub Tag
`v2.0.0-canary.10` Prerelease			GitHub Tag
`v2.0.0-canary.9` Prerelease			GitHub Tag
`v2.0.0-canary.8` Prerelease			GitHub Tag
`v2.0.0-canary.7` Prerelease			GitHub Tag
`v2.0.0-canary.6` Prerelease			GitHub Tag
`v2.0.0-canary.5` Prerelease			GitHub Tag
`v2.0.0-canary.4` Prerelease			GitHub Tag
`v2.0.0-canary.3` Prerelease			GitHub Tag
`v2.0.0-canary.2` Prerelease			GitHub Tag
`v2.0.0-canary.1` Prerelease			GitHub Tag
`v2.0.0-beta.3` Prerelease		2023 Jan 30	GitHub Release
`v2.0.0-beta.2` Prerelease		2023 Jan 26	GitHub Release
`v2.0.0-beta.1` Prerelease		2023 Jan 18	GitHub Release
`v1.0.2`	Docs	2022 Aug 16	GitHub Release
`v1.0.1`	Docs	2022 Apr 18	GitHub Release
`v1.0.1-canary.4` Prerelease			GitHub Tag
`v1.0.1-canary.3` Prerelease			GitHub Tag
`v1.0.1-canary.2` Prerelease			GitHub Tag
`v1.0.1-canary.1` Prerelease			GitHub Tag
`v1.0.0`	Docs	2022 Jan 08	GitHub Release
`v1.0.0-canary.50` Prerelease			GitHub Tag
`v1.0.0-canary.49` Prerelease			GitHub Tag
`v1.0.0-canary.48` Prerelease			GitHub Tag
`v1.0.0-canary.47` Prerelease			GitHub Tag
`v1.0.0-canary.46` Prerelease			GitHub Tag
`v1.0.0-canary.45` Prerelease			GitHub Tag
`v1.0.0-canary.44` Prerelease			GitHub Tag
`v1.0.0-canary.43` Prerelease			GitHub Tag
`v1.0.0-canary.42` Prerelease			GitHub Tag
`v1.0.0-canary.41` Prerelease			GitHub Tag
`v1.0.0-canary.40` Prerelease			GitHub Tag
`v1.0.0-canary.39` Prerelease			GitHub Tag
`v1.0.0-canary.38` Prerelease			GitHub Tag
`v1.0.0-canary.37` Prerelease			GitHub Tag
`v1.0.0-canary.36` Prerelease			GitHub Tag
`v1.0.0-canary.35` Prerelease			GitHub Tag
`v1.0.0-canary.34` Prerelease			GitHub Tag
`v1.0.0-canary.33` Prerelease			GitHub Tag
`v1.0.0-canary.32` Prerelease			GitHub Tag
`v1.0.0-canary.31` Prerelease			GitHub Tag
`v1.0.0-canary.30` Prerelease			GitHub Tag
`v1.0.0-canary.29` Prerelease			GitHub Tag
`v1.0.0-canary.28` Prerelease			GitHub Tag
`v1.0.0-canary.27` Prerelease			GitHub Tag
`v1.0.0-canary.26` Prerelease			GitHub Tag
`v1.0.0-canary.25` Prerelease			GitHub Tag
`v1.0.0-canary.24` Prerelease			GitHub Tag
`v1.0.0-canary.23` Prerelease			GitHub Tag
`v1.0.0-canary.22` Prerelease			GitHub Tag
`v1.0.0-canary.21` Prerelease			GitHub Tag
`v1.0.0-canary.20` Prerelease			GitHub Tag
`v1.0.0-canary.19` Prerelease			GitHub Tag
`v1.0.0-canary.18` Prerelease			GitHub Tag
`v1.0.0-canary.17` Prerelease			GitHub Tag
`v1.0.0-canary.16` Prerelease			GitHub Tag
`v1.0.0-canary.15` Prerelease			GitHub Tag
`v1.0.0-canary.14` Prerelease			GitHub Tag
`v1.0.0-canary.13` Prerelease			GitHub Tag
`v1.0.0-canary.12` Prerelease			GitHub Tag
`v1.0.0-canary.11` Prerelease			GitHub Tag
`v1.0.0-canary.10` Prerelease			GitHub Tag
`v1.0.0-canary.9` Prerelease			GitHub Tag
`v1.0.0-canary.8` Prerelease			GitHub Tag
`v1.0.0-canary.7` Prerelease			GitHub Tag
`v1.0.0-canary.6` Prerelease			GitHub Tag
`v1.0.0-canary.5` Prerelease			GitHub Tag
`v1.0.0-canary.4` Prerelease			GitHub Tag
`v1.0.0-canary.3` Prerelease			GitHub Tag
`v1.0.0-canary.1` Prerelease			GitHub Tag
`v1.0.0-beta.10` Prerelease			GitHub Tag
`v1.0.0-beta.9` Prerelease			GitHub Tag
`v1.0.0-beta.8` Prerelease			GitHub Tag
`v1.0.0-beta.7` Prerelease			GitHub Tag
`v1.0.0-beta.6` Prerelease			GitHub Tag
`v1.0.0-beta.5` Prerelease			GitHub Tag
`v1.0.0-beta.4` Prerelease			GitHub Tag
`v1.0.0-beta.3` Prerelease			GitHub Tag
`v1.0.0-beta.2` Prerelease			GitHub Tag
`v1.0.0-beta.1` Prerelease			GitHub Tag
`v0.12.1`	Docs	2021 Mar 19	GitHub Release
`v0.12.0`	Docs	2021 Mar 19	GitHub Release
`v0.11.1`	Docs	2020 Oct 22	GitHub Release
`v0.11.0`	Docs	2020 May 10	GitHub Release
`v0.11.0-beta.4` Prerelease			GitHub Tag
`v0.11.0-beta.3` Prerelease			GitHub Tag
`v0.11.0-beta.2` Prerelease			GitHub Tag
`v0.11.0-beta.1` Prerelease			GitHub Tag
`v0.10.0`	Docs	2020 Jan 07	GitHub Release
`v0.10.0-beta.2` Prerelease		2020 Jan 04	GitHub Release
`v0.10.0-beta.1` Prerelease		2019 Dec 09	GitHub Release
`v0.9.0`	Docs	2019 Aug 27	GitHub Release
`v0.9.0-beta.3` Prerelease			GitHub Tag
`v0.9.0-beta.2` Prerelease		2019 Aug 17	GitHub Release
`v0.9.0-beta.1` Prerelease		2019 Jul 26	GitHub Release
`v0.8.3`	Docs	2019 May 04	GitHub Release
`v0.8.2`	Docs	2019 Apr 09	GitHub Release
`v0.8.1`	Docs	2019 Apr 06	GitHub Release
`v0.8.0`	Docs	2019 Apr 04	GitHub Release
`v0.8.0-beta.1` Prerelease			GitHub Tag
`v0.7.1`	Docs	2019 Jan 12	GitHub Release
`v0.7.0`	Docs	2019 Jan 11	GitHub Release
`v0.6.0`	Docs	2018 Nov 25	GitHub Release
`v0.5.4`	Docs	2018 Sep 28	GitHub Release
`v0.5.3`	Docs	2018 Aug 29	GitHub Release
`v0.5.2`	Docs	2018 Aug 15	GitHub Release
`v0.5.1`	Docs	2018 Aug 15	GitHub Release
`v0.5.0`	Docs	2018 Jul 05	GitHub Release
`v0.4.0`	Docs	2018 Jun 20	GitHub Release
`v0.3.6`	Docs	2018 Jun 07	GitHub Release
`v0.3.5`	Docs	2018 May 22	GitHub Release
`v0.3.4`	Docs	2018 May 11	GitHub Release
`v0.3.3`	Docs	2018 Apr 17	GitHub Release
`v0.3.2`			GitHub Tag
`v0.3.1`	Docs	2018 Apr 05	GitHub Release
`v0.3.0`	Docs	2018 Mar 26	GitHub Release
`v0.2.15`	Docs	2018 Mar 06	GitHub Release
`v0.2.14`	Docs	2018 Feb 16	GitHub Release
`v0.2.13`	Docs
`v0.2.12`	Docs
`v0.2.11`	Docs
`v0.2.10`	Docs	2018 Jan 25	GitHub Release
`v0.2.9`	Docs
`v0.2.8`	Docs
`v0.2.7`	Docs	2018 Jan 17	GitHub Release
`v0.2.6`	Docs	2018 Jan 12	GitHub Release
`v0.2.5`	Docs
`v0.2.4`	Docs
`v0.2.3`	Docs
`v0.2.2`	Docs	2018 Jan 09	GitHub Release
`v0.2.1`	Docs
`v0.2.0`	Docs
`v0.1.9`	Docs
`v0.1.8`	Docs
`v0.1.7`	Docs
`v0.1.6`	Docs
`v0.1.5`	Docs
`v0.1.4`	Docs
`v0.1.3`	Docs
`v0.1.2`	Docs
`v0.1.1`	Docs
`v0.1.0`	Docs

Command Line Usage

2026-08-24T19:50:14Z

Command Line Usage

Prerequisites

Eleventy runs in a Terminal application. Well, wait—what is a Terminal?
Have you already installed Eleventy?

Here’s the first command you can enter in your Terminal application to run Eleventy:

npm pnpm yarn

# Searches the current directory, outputs to ./_site
npx @11ty/eleventy

# `npx @11ty/eleventy` is the same as:
npx @11ty/eleventy --input=. --output=_site

# Searches the current directory, outputs to ./_site
pnpm exec eleventy

# `pnpm exec eleventy` is the same as:
pnpm exec eleventy --input=. --output=_site

# Searches the current directory, outputs to ./_site
yarn exec eleventy

# `yarn exec eleventy` is the same as:
yarn exec eleventy --input=. --output=_site

Read more about --input and --output. Note that setting the input and output directories via config file is preferred.

A hypothetical template.md in the current directory would be rendered to _site/template/index.html. Read more at Permalinks.

npm pnpm yarn

# Use only a subset of template types
npx @11ty/eleventy --formats=md,html,ejs

# Don’t process any formats
npx @11ty/eleventy --formats=

# Find out the most up-to-date list of commands (there are more)
npx @11ty/eleventy --help

# Use only a subset of template types
pnpm exec eleventy --formats=md,html,ejs

# Don’t process any formats
pnpm exec eleventy --formats=

# Find out the most up-to-date list of commands (there are more)
pnpm exec eleventy --help

# Use only a subset of template types
yarn exec eleventy --formats=md,html,ejs

# Don’t process any formats
yarn exec eleventy --formats=

# Find out the most up-to-date list of commands (there are more)
yarn exec eleventy --help

The default for --formats= changed in v3.0.0 from an alias of * to an empty set.

Re-run Eleventy when you save

npm pnpm yarn

# Add a web server to apply changes and
# refresh automatically. We’ll also --watch for you.
npx @11ty/eleventy --serve

# Change the web server’s port—use localhost:8081
npx @11ty/eleventy --serve --port=8081

# Watch and re-run when files change, without the web server.
npx @11ty/eleventy --watch

# Add a web server to apply changes and
# refresh automatically. We’ll also --watch for you.
pnpm exec eleventy --serve

# Change the web server’s port—use localhost:8081
pnpm exec eleventy --serve --port=8081

# Watch and re-run when files change, without the web server.
pnpm exec eleventy --watch

# Add a web server to apply changes and
# refresh automatically. We’ll also --watch for you.
yarn exec eleventy --serve

# Change the web server’s port—use localhost:8081
yarn exec eleventy --serve --port=8081

# Watch and re-run when files change, without the web server.
yarn exec eleventy --watch

`--quiet` if the Output is Too Noisy

npm pnpm yarn

# Shhhhh—Don’t log so much to the console
npx @11ty/eleventy --quiet

# Shhhhh—Don’t log so much to the console
pnpm exec eleventy --quiet

# Shhhhh—Don’t log so much to the console
yarn exec eleventy --quiet

`--dryrun` to do a Little Testing

Runs without writing to the file system. Useful when debugging.

npm pnpm yarn

# Run Eleventy but don’t write any files
npx @11ty/eleventy --dryrun

# Run Eleventy but don’t write any files
pnpm exec eleventy --dryrun

# Run Eleventy but don’t write any files
yarn exec eleventy --dryrun

`--config` to Change the Config file name

npm pnpm yarn

# Override the default eleventy project config filename (.eleventy.js)
npx @11ty/eleventy --config=myeleventyconfig.js

# Override the default eleventy project config filename (.eleventy.js)
pnpm exec eleventy --config=myeleventyconfig.js

# Override the default eleventy project config filename (.eleventy.js)
yarn exec eleventy --config=myeleventyconfig.js

`--to` can output JSON Added in v1.0.0

npm pnpm yarn

# Output a JSON structure (does not write to the file system)
npx @11ty/eleventy --to=json

# Output a Newline Deliminated JSON structure (does not write to the file system)
npx @11ty/eleventy --to=ndjson

# Default behavior (Output to file system)
npx @11ty/eleventy --to=fs

# Output a JSON structure (does not write to the file system)
pnpm exec eleventy --to=json

# Output a Newline Deliminated JSON structure (does not write to the file system)
pnpm exec eleventy --to=ndjson

# Default behavior (Output to file system)
pnpm exec eleventy --to=fs

# Output a JSON structure (does not write to the file system)
yarn exec eleventy --to=json

# Output a Newline Deliminated JSON structure (does not write to the file system)
yarn exec eleventy --to=ndjson

# Default behavior (Output to file system)
yarn exec eleventy --to=fs

`--incremental` for Partial Incremental Builds

npm pnpm yarn

# *Repeat* builds only operate on files that have changed
npx @11ty/eleventy --watch --incremental
npx @11ty/eleventy --serve --incremental

# Skip the initial full build with `--ignore-initial`
npx @11ty/eleventy --serve --incremental --ignore-initial

# Pass in a template path, watch/serve not required
# Added in v3.0.0
npx @11ty/eleventy --incremental=myfile.md

# *Repeat* builds only operate on files that have changed
pnpm exec eleventy --watch --incremental
pnpm exec eleventy --serve --incremental

# Skip the initial full build with `--ignore-initial`
pnpm exec eleventy --serve --incremental --ignore-initial

# Pass in a template path, watch/serve not required
# Added in v3.0.0
pnpm exec eleventy --incremental=myfile.md

# *Repeat* builds only operate on files that have changed
yarn exec eleventy --watch --incremental
yarn exec eleventy --serve --incremental

# Skip the initial full build with `--ignore-initial`
yarn exec eleventy --serve --incremental --ignore-initial

# Pass in a template path, watch/serve not required
# Added in v3.0.0
yarn exec eleventy --incremental=myfile.md

Read more about incremental builds. Related GitHub #3324

`--ignore-initial` to run Eleventy without an Initial Build Added in v2.0.0

Be wary of any file changes that happened while Eleventy wasn’t running!

npm pnpm yarn

# Don’t build when Eleventy starts, only build on file changes
npx @11ty/eleventy --watch --ignore-initial
npx @11ty/eleventy --serve --ignore-initial

# Works great with Incremental
npx @11ty/eleventy --serve --incremental --ignore-initial

# Don’t build when Eleventy starts, only build on file changes
pnpm exec eleventy --watch --ignore-initial
pnpm exec eleventy --serve --ignore-initial

# Works great with Incremental
pnpm exec eleventy --serve --incremental --ignore-initial

# Don’t build when Eleventy starts, only build on file changes
yarn exec eleventy --watch --ignore-initial
yarn exec eleventy --serve --ignore-initial

# Works great with Incremental
yarn exec eleventy --serve --incremental --ignore-initial

Deeper insight into Eleventy Internals

You can use the DEBUG environment variable to enable the special debug log output, allowing deeper insight into Eleventy’s internals. For simplicity this example is using the cross-env package.

npm pnpm yarn

npx cross-env DEBUG=Eleventy:* npx @11ty/eleventy --dryrun

pnpm exec cross-env DEBUG=Eleventy:* pnpm exec @11ty/eleventy --dryrun

yarn exec cross-env DEBUG=Eleventy:* yarn exec @11ty/eleventy --dryrun

Learn more about Eleventy’s Debug Mode log output.

Using the Same Input and Output

Yes, you can use the same input and output directories, like so:

npm pnpm yarn

# Parse and write Markdown to HTML, respecting directory structure.
npx @11ty/eleventy --input=. --output=. --formats=md

# Parse and write Markdown to HTML, respecting directory structure.
pnpm exec eleventy --input=. --output=. --formats=md

# Parse and write Markdown to HTML, respecting directory structure.
yarn exec eleventy --input=. --output=. --formats=md

WARNING

Careful with --formats=html here! If you run Eleventy more than once, we will attempt to process your new output files as input files (which will throw errors). Read more at the HTML template docs.

Incremental

2026-08-24T19:50:14Z

Incremental Builds

Incremental builds via the command line flag --incremental perform a partial build operating only on files that have changed to improve build times when doing local development.

Let’s check in on the current capabilities and the roadmap:

Templates (Incremental template builds):
- If you create/update a template file, Eleventy will run the build for that file and only that file.
- Layouts Added in v2.0.0: When you change a layout file, any templates using that layout file are rebuilt.
- Template Dependencies Added in v2.0.0Any templates using a dependency mapped via the addDependencies method will be rebuilt when those dependencies change.
  - Added in v1.0.0This feature was previously exposed as part of the API for Custom template extensions via the isIncrementalMatch function.
  - Exceptions for Includes: If the created/updated file is in your Includes or Layouts directories, a full build will run (unless a known Eleventy layout file Added in v2.0.0).
- Collections Added in v2.0.0: When you add or delete a tag from a template, any templates using that collection tag (as declared by pagination.data or eleventyImport.collections) will be rebuilt.
Passthrough Copy (Incremental passthrough copy) :
- Only copy a passthrough copy file when it actively changed. Don’t run a template or full build if only a passthrough copy file has changed.
- When running a template build, skip the passthrough copy step.
- Added in v2.0.0 Passthrough copy can be emulated during --serve to speed up both incremental and non-incremental builds. It was decided not to ship incremental passthrough copy as the default behavior (#1109), instead deferring to this emulated copy feature.
Configuration File
- If you create/update your Eleventy configuration file, a full build will run.
Don’t build on startup: Added in v2.0.0 --ignore-initial was added and works great with --incremental.
Explicit Incremental Added in v3.0.0 Pass in a filename to only build an incremental for one file (and it’s dependencies) with --incremental=filename (more in #3324)
- Pre-release only: v4.0.0-alpha.8Added support for multiple incremental files (also called Batched Incremental) with --incremental=file1 --incremental=file2 or --incremental=file1,file2 (more in #4274)

Additional Template Syntax Specific Features

The previously stated incremental features are implemented in Eleventy core and are available to all template languages. Some template types offer additional --incremental build support:

WebC: deep knowledge of the full component dependency graph allows us to smartly build templates that use a component when that component is changed.

🗓 To Do

Cold Start Incremental: --incremental does a full build to start out to provide a fresh starting point to work from. This feature would save the state of the build to the file system for faster cold starts. #984
Incremental on a Build Server: Cache the output folder between builds on a CI server like Netlify and only process/write templates that have changed since the last build. #2775
Global/directory/template Data file usage mapped to templates #2706
Template types
- 11ty.js: Map JavaScript dependencies
- liquid: Dependency mapping for Liquid templates ({% include %}, etc)
- njk Dependency mapping for Nunjucks templates ({% include %}, etc): more at Issue #3804
Collections dependencies improvements: while we have eleventyImport.collections to declaratively log collections dependencies, we may be able to dive deeper into template syntax APIs to find the symbols in use. #1615 Alternatively we may be able to change the collections API to use Proxies to get smarter about this in an easier way (though previous experiments with this for eleventyComputed failed in some languages).
Render plugin: {% renderFile %} dependencies
Stretch goal: Pagination-level incremental that operates on a subset of data #1087

Transforms

2026-08-24T19:50:14Z

Transforms

Transforms can modify a template’s output. For example, use a transform to format/prettify an HTML file with proper whitespace.

The provided transform function must return the original or transformed content.

eleventy.config.js

ESM CommonJS

export default function(eleventyConfig) {
	// Can be sync or async
	eleventyConfig.addTransform("transform-name", async function (content) {
		console.log(this.page.inputPath);

		// Caution: this could be `false` (from permalink)
		console.log(this.page.outputPath);

		// No changes made, return as-is
		return content;
	});
};

module.exports = function(eleventyConfig) {
	// Can be sync or async
	eleventyConfig.addTransform("transform-name", async function (content) {
		console.log(this.page.inputPath);

		// Caution: this could be `false` (from permalink)
		console.log(this.page.outputPath);

		// No changes made, return as-is
		return content;
	});
};

Access to Eleventy’s page variable (via this.page) was added in Eleventy v2.0. For previous versions, consult the older versions of the docs.

Running Transforms Manually

Added in v3.0.0 The renderTransforms universal filter allows projects to run transforms manually on blocks of arbitrary HTML content.

Order of Execution

Transforms are executed in order of insertion in your configuration file.

eleventyConfig.addTransform("first", () => {});
eleventyConfig.addTransform("second", () => {});
eleventyConfig.addTransform("third", () => {});

Plugins

Transforms added via plugins are inserted via the second configuration stage for plugins.

eleventyConfig.addPlugin(eleventyConfig => {
	eleventyConfig.addTransform("third", () => {});
});
eleventyConfig.addTransform("first", () => {});
eleventyConfig.addTransform("second", () => {});

Examples

Minify HTML Output

eleventy.config.js

ESM CommonJS

import htmlmin from "html-minifier-terser";

export default function (eleventyConfig) {
	eleventyConfig.addTransform("htmlmin", function (content) {
		// String conversion to handle `permalink: false`
		if ((this.page.outputPath || "").endsWith(".html")) {
			let minified = htmlmin.minify(content, {
				useShortDoctype: true,
				removeComments: true,
				collapseWhitespace: true,
			});

			return minified;
		}

		// If not an HTML output, return content as-is
		return content;
	});
};

const htmlmin = require("html-minifier-terser");

module.exports = function (eleventyConfig) {
	eleventyConfig.addTransform("htmlmin", function (content) {
		// String conversion to handle `permalink: false`
		if ((this.page.outputPath || "").endsWith(".html")) {
			let minified = htmlmin.minify(content, {
				useShortDoctype: true,
				removeComments: true,
				collapseWhitespace: true,
			});

			return minified;
		}

		// If not an HTML output, return content as-is
		return content;
	});
};

Note that html-minifier-terser has a significant number of options, most of which are disabled by default.

Testmonials

2026-08-24T19:50:14Z

Testimonials

Don’t just take my word for it. 🌈 Listen to what these happy developers are saying about Eleventy:

“The Eleventy + Netlify combo continues to be 🤌” —Dan Mall

“I tried Eleventy last night on a personal project and today we implemented it on a (non-public facing) client project. It's really good.” —Cody Peterson

“I think what's great about Eleventy is how it was able to simplify SSGs to just 2 concepts: data sources and templates.” —Matthew Phillips

“Eleventy… makes my life so much easier.” —HJ Chen

Read the replies to: “Fans of Eleventy.... why do you like it better than other static site generators?”

“Eleventy is a killer static site generator. That’s all.” —Sara Soueidan

“Eleventy and web components go really, really well together.” —Justin Fagnani

“[Eleventy is] a platform that legitimately built things in the way that I thought and worked more than anything else out there, and with every new feature it's like my mind gets read.” —Bryan Robinson

“I heard Eleventy was good” —Lach Zeatherman

“Seriously can't remember enjoying using a Static Site Generator this much. Yes Hugo is rapid, but this is all so logical. It feels like it was designed by someone who has been through lots of pain and success using other SSGs.” —Phil Hawksworth

“Every time I make something with Eleventy it makes me smile. I think that might be to do with its focus on simplicity.” —Phil Hawksworth

“Eleventy + Netlify have become my new workflow for static sites. I think I'm in love.” —Mina Markham

“Eleventy is my fave.” —Tatiana Mac

“I actually used Eleventy for the first time this week. Loved it.” —Paul Lewis

“Eleventy is as close as we’ve gotten to how the web was always meant to be built (ya’ know, once we realized the value of templates and JavaScript).” —Reuben L. Lillie

“2022 winner of the Google Open Source Peer Bonus Award” —Google

“Think the reason everyone is loving [Eleventy] so much (myself included) is that it doesn't come with a prescription about data sources or template rendering.” —Brian Leroux

“Jekyll is dead to me” —Andy Bell

“Just the kind of simple / common sense tool I love. The data/folder hierarchy mechanism is super obvious and elegant.” —Heydon Pickering

“Holy cow! Eleventy is so crazy simple to work with.” —Will Riley

“Eleventy is almost fascinatingly simple.” —Chris Coyier

“Just gave Eleventy a first run/try and I must say it's pretty dang awesome. Especially for someone like me, who is most familiar with HTML and CSS and some JS. ❤️” —Marco Hengstenberg

“I use Eleventy on almost every project at this point and I love it.” —Lea Verou

“After a day or so tweaking my existing build, here is a preview of the site running on Eleventy. I'm sold! The main thing to me was the ability to run custom JavaScript logic to sort, filter, and augment data in collections.” —Eduardo Bouças

“I like Eleventy. (I hope that was enough to get me on the testimonials page.)” —Steve Gardner

“I looked into and actively tried using various static site generators for this project. Eleventy was the only one I could find that gave me the fine-grained control I needed at blazingly fast build times.” —Mathias Bynens

“Don’t tell Zach I said it but Eleventy is seeming fresh as hell so far” —Mat Marquis

“2018 winner of the Google Open Source Peer Bonus Award” —Google

“Eleventy is absolutely wonderful. It’s by far the nicest static site generator I’ve used in what feels like forever.” —Addy Osmani

“I've been digging into Eleventy, a new static site generator. Really like the way it handles pagination!” —James Williamson

“Easily one of my favorite open source projects ever!” —Tyler Sticka

“#1 Product of the Day (May 2022)” —Product Hunt

“Just got through moving a project to Eleventy. Never used nunjucks or a static site generator before, but it was so easy. This will make my life so much easier.” —Micah Mills

“2019 winner of the Google Open Source Peer Bonus Award” —Google

“I challenged myself to build the site in a day. I started at noon on Saturday and had something launched by 1am Saturday night. Built on [Eleventy] served by GitHub Pages, using [TravisCi] to deploy.” —Snook

“It's clean, elegant, easy to use, and does just enough to be useful without getting in the way. Excellent work 😊” —Timothy Miller

“I really like the flexibility Eleventy offers in comparison to my previous Jekyll build.” —Alex Carpenter

Eleventy Documentation

WebC

Why use WebC?

Performance

Compatible with Standards

Authoring

Resources

Installation

Syntax highlighting

Usage

Add a new .webc file

Non-traditional WebC usage

Use the Render plugin

Pre-process HTML input as WebC

Post-process HTML output as WebC

Components and output

HTML-only components

Asset bundling

webc:keep

webc:nokeep

webc:is

webc:import

Attributes, props and slots

Which one to use

Attributes and webc:root

Override the host component tag

Props (Properties)

Dynamic attributes and properties

@attributes

Slots

Named slots

Rendering content

@html

@raw

@text

webc:if

webc:elseif and webc:else

webc:for

Scripts and styles

webc:setup

webc:type

webc:type="js"

Extra data for JavaScript render functions

webc:type="11ty" and 11ty:type

Helper functions

Eleventy-provided helpers

Supply your own helper

webc:scoped

webc:bucket

Opting out of WebC processing

webc:raw

webc:ignore

Server-only comments

Subtleties and limitations

Void elements

Head components

Table components

Rendering modes

Differences from HTML parsing

Eleventy + WebC Features

Front Matter

Defining Components

Global no-import Components

Declaring Components in Front Matter

Official WebC Components

Eleventy Data Cascade

CSS and JS (Bundler mode)

Bundle Code Ordering

Access Bundles in other Template Engines

Asset bucketing

Cascading Asset Buckets

Conflicts and hoisting

Use with is-land

From the Community

RSS

RSS Plugin

Feature highlights

Installation

Virtual Template

Manual Template

Add a new `.webc` file

`webc:keep`

`webc:nokeep`

`webc:is`

`webc:import`

Attributes and `webc:root`

`@attributes`

`@html`

`@raw`

`@text`

`webc:if`

`webc:elseif` and `webc:else`

`webc:for`

`webc:setup`

`webc:type`

`webc:type="js"`

`webc:type="11ty"` and `11ty:type`

`webc:scoped`

`webc:bucket`

`webc:raw`

`webc:ignore`

Use with `is-land`

`.gitignore`

Advanced `chokidar` Configuration

`--quiet` if the Output is Too Noisy

`--dryrun` to do a Little Testing

`--config` to Change the Config file name

`--to` can output JSON Added in v1.0.0

`--incremental` for Partial Incremental Builds

`--ignore-initial` to run Eleventy without an Initial Build Added in v2.0.0