Eleventy Documentation

Eleventy automatically provides several data objects to your templates to help manage content, pagination, and metadata. The primary supplied data objects are:

• pkg: Contains the values from your local project's package.json.
• pagination: Used via the pagination key in front matter to divide data into chunks for multiple output pages.
• collections: A list of all content, grouped by tags.
• page: Contains metadata about the current page being processed.
• eleventy: Contains Eleventy-specific metadata and environment information (added in v1.0.0).

Eleventy projects can be deployed using several different methods:

Jamstack Providers

These providers automatically trigger a build when you commit to source control (GitHub, GitLab, etc.) and deploy the output directory.

Classic Web Hosts

Eleventy works with any host that supports static files. Deployment is not automatic; you must run the Eleventy build command locally and manually upload the output directory (defaults to _site) to the host.

Web Editors

Platforms like Stackblitz allow you to run and edit Eleventy projects directly in your browser.

<is-land> is a framework-independent implementation of the Islands Architecture. It provides a way to perform partial hydration, allowing you to smartly and efficiently load and initialize client-side components only where needed.

Key characteristics include:

• Zero dependencies and a small footprint (1.83 kB compressed).
• Framework independent: It is not tightly coupled to a specific server framework or site generator.
• SSR Friendly: Supports server-rendered component examples for frameworks like Lit, Svelte, Vue, and Preact.

Eleventy uses an extensible architecture that allows you to use one or more template languages within the same project. This means you are not locked into a single syntax; you can mix different template engines (like Liquid, Nunjucks, or Handlebars) to suit different parts of your site or specific content needs.

Note that while core functionality is provided, many template languages require the installation of specific Eleventy plugins to be used.

The .cache folder is used by the Eleventy Fetch plugin and Eleventy Image plugin to avoid repeating expensive network requests or image processing. Since this folder is typically excluded from Git, it will be empty on most build servers by default.

To improve build times, you can persist this folder using provider-specific methods:

• Cloudflare Pages: Automatically preserves the .cache folder by default.
• Vercel: Zero-configuration support if the Eleventy framework is detected.
• GitHub Pages: Use the GitHub cache action.
• Netlify: Use netlify-plugin-cache.
• CloudCannon: Use 'Preserved paths'.

Speeding up Eleventy Image: If you write your Eleventy Image output to your Eleventy output directory (e.g., ./_site/img/), you can also persist that folder to reuse the Eleventy Image disk cache.

In Eleventy, data is not just defined in a single place; it is merged from multiple different sources before a template is rendered. This process is known as the Data Cascade.

When multiple sources provide data for the same key, Eleventy follows a precedence rule where the "leaf template" (the specific file being rendered) takes precedence over higher-level sources like layouts or directory data files.

For example, if a template file defines title: My Post and its layout defines title: Default Title, the rendered output will use My Post.

The rebranding of Eleventy to Build Awesome does not break existing workflows. The project is committed to maintaining full compatibility with the existing Eleventy community and ecosystem. Specifically:

• Plugins: You can continue to use existing Eleventy plugins with Build Awesome.
• Build Commands: Existing Eleventy build commands will remain compatible.
• Upgrades: Major version upgrades (e.g., moving from Eleventy v4 to Build Awesome v4) will continue to follow the established pattern of smooth, well-documented transitions, supported by the Upgrade Helper plugin.

Eleventy uses the gray-matter npm package to parse front matter. While Eleventy provides default settings, you can pass additional gray-matter options to customize how front matter is handled. This allows for advanced features like using different parsing engines or defining custom excerpt behaviors.

For a full list of supported options, refer to the gray-matter documentation.

You can build a navigation tree by adding an eleventyNavigation object to your template's front matter or a data directory file.

• key: A unique string identifier for the navigation item.
• parent: The key of the item this template should be nested under. If omitted, the item is a top-level root item.
• title: (Optional) The display text for the link. If omitted, the key is used as the link text.
• order: (Optional) An integer to control the sort order. Defaults to 0. Lower numbers appear first.
• url: (Optional) An external URL to link to. When using this, you should typically set permalink: false to prevent Eleventy from trying to generate a file for this template.

# Example of a nested item with custom title and order
eleventyNavigation:
  key: Humans
  parent: Mammals
  title: All of the Humans
  order: 1