Eleventy (11ty)

Eleventy is a simple static site generator written in JavaScript. It transforms a directory of templates into HTML. It is designed as an alternative to Jekyll and supports a wide variety of template languages including:

• HTML
• Markdown
• JavaScript
• Liquid
• Nunjucks

It also supports various addons for technologies like WebC, Sass, Vue, Svelte, TypeScript, and JSX.

You can install Eleventy using npm. The project supports both the new @awesome.me/buildawesome package name and the legacy @11ty/eleventy package name for backwards compatibility.

To install for a development project, use the --save-dev flag.

npm install @awesome.me/buildawesome --save-dev

# Backwards compatible here too:
npm install @11ty/eleventy --save-dev

Install the browser-friendly version of Eleventy, @11ty/client, using npm. This package provides a client-side experience for Eleventy functionality.

npm install @11ty/client --save

Eleventy searches for configuration files in a specific order to determine the project settings. If no configuration path is manually specified, it looks for:

1. buildawesome.config.js (or other eligible JS paths via expandEligibleJavaScriptFilePaths)
2. .eleventy.js
3. eleventy.config.js (or other eligible JS paths via expandEligibleJavaScriptFilePaths)

If a configuration file is manually specified via the API but cannot be found, Eleventy will throw a ConfigError.

The --to flag determines how Eleventy delivers the processed content:

1. fs (Default): Writes the generated files to the file system at the location specified by --output. Note that using fs:templates will skip the passthrough copy step.
2. json: Instead of writing files, Eleventy processes the content and outputs a JSON representation of the build to stdout.

Note: The --to json mode is incompatible with --serve or --watch modes.

In watch mode, Eleventy monitors files to determine if a full configuration reset is required. A reset is triggered if:

1. A local project configuration file (e.g., eleventy.config.js) is changed.
2. A file matching the globs defined in userConfig.watchTargetsConfigReset is changed.
3. A dependency of a configuration file is changed.

When a reset is triggered, Eleventy emits the buildawesome.reset event, reloads the global configuration, and restarts the engine to ensure all new configuration settings are applied.

Eleventy allows you to modify a template engine's library instance after it has been loaded but before it is used. This is done via the libraryAmendments key in your configuration object.

Amendments are functions that receive the engineLib as an argument. This is useful for adding custom filters, tags, or global variables to engines like Liquid or Nunjucks.

Example configuration structure:

// Inside your Eleventy configuration
module.exports = function(eleventyConfig) {
  // The TemplateEngine will look for amendments under its specific name
  // e.g., if the engine name is 'liquid'
  eleventyConfig.addConfig({
    libraryAmendments: {
      liquid: [
        (engineLib) => {
          // Modify engineLib here
        }
      ]
    }
  });
};

Eleventy can watch JavaScript dependencies used within your templates and data files. This ensures that if a JS file imported by a template or global data file changes, the project rebuilds.

To control this behavior, use:

• eleventyConfig.setWatchJavaScriptDependencies(false) to disable watching JS dependencies (this can improve performance).
• eleventyConfig.shouldSpiderJavaScriptDependencies() to check if the engine is currently configured to spider these dependencies.

To create a new template engine for Eleventy, you should extend the TemplateEngine class. At a minimum, you must implement the async compile() method.

Note that TemplateEngine is designed to be used internally by Eleventy's engine management system, typically initialized with a name and an eleventyConfig instance.

// Conceptual implementation
class MyCustomEngine extends TemplateEngine {
  async compile(str, data) {
    // Your logic to transform 'str' using 'data'
    return renderedString;
  }
}

/**
 * @abstract
 * @return {Promise}
 */
async compile() {
	throw new Error("compile() must be implemented by engine");
}