repository·main·Indexed 12 days ago
https://github.com/11ty/buildawesomeA JavaScript-based static site generator that transforms various template types into HTML. It supports multiple template languages, is extensible via plugins, and provides both a CLI and a programmatic API via the Core and CoreMinimal classes. Version 4.0.0-alpha.10 includes a browser-friendly client implementation (@11ty/client) with support for Markdown, Nunjucks, and Liquid.
You can install Build Awesome (Eleventy) via npm. The package @awesome.me/buildawesome is the current naming convention, but @11ty/eleventy remains available for backwards compatibility.
npm install @awesome.me/buildawesome --save-dev
# Backwards compatible version:
npm install @11ty/eleventy --save-devInstall the browser-friendly version of Eleventy using npm. This package provides a client-side implementation of the static site generator capabilities.
npm install @11ty/client --saveThe TemplateEngine supports applying amendments to the underlying engine library. These amendments are defined in the configuration under config.libraryAmendments[this.name].
When setEngineLib(engineLib) is called, the engine iterates through the array of amendment functions provided in the configuration for that specific engine name and executes them, passing the engineLib as an argument.
When running in watch mode, Eleventy monitors specific files to determine if a full configuration reset is required. A reset is triggered if:
buildawesome.config.js) is modified.userConfig.watchTargetsConfigReset is modified.When a reset is triggered, Eleventy emits the buildawesome.reset event, reloads the global configuration, and restarts the build process to ensure all new configuration settings are applied.
The configuration follows a specific hierarchy and merging logic:
customRootConfig if provided)..eleventy.js). It supports both a function return (e.g., module.exports = function(eleventyConfig) { ... }) and a direct object export (e.g., export const config = { ... }).userConfig and modify the resulting configuration.setPathPrefix or setDirectories) take precedence over the values returned by the configuration files.Note on Template Formats:
templateFormats can be set via the config object.templateFormatsAdded is additive and is used to append new formats to the existing list.The RenderPlugin allows you to render an Eleventy template string or file inside another template using shortcodes or filters.
To use it, add it to your Eleventy configuration using $config.addPlugin(RenderPlugin, options).
Plugin Options:
tagName (string, default: "renderTemplate"): The name of the shortcode used to render a template string.tagNameFile (string, default: "renderFile"): The name of the shortcode used to render a template file.filterName (string, default: "renderContent"): The name of the async filter used to render template strings.templateConfig (TemplateConfig, optional): A configuration object.accessGlobalData (boolean, default: false): If true, the rendered template will have access to the parent template's data cascade.import RenderPlugin from "@11ty/eleventy/render-plugin";
export default function (eleventyConfig) {
eleventyConfig.addPlugin(RenderPlugin, {
tagName: "renderTemplate",
tagNameFile: "renderFile",
accessGlobalData: true
});
};The Build Awesome (Eleventy) CLI allows you to build, watch, or serve your site from the command line. It supports various modes including standard builds, file watching, and a local development server. You can also output the build results as JSON instead of writing to the file system.
# Example: Standard build
eleventy
# Example: Serve the site on a specific port
eleventy --serve --port 8080
# Example: Watch for changes
eleventy --watch
# Example: Output build data as JSON
eleventy --to jsonYou can customize the underlying file watcher behavior by providing a chokidarConfig object within your Eleventy configuration.
By default, the watcher uses the following settings:
ignoreInitial: trueawaitWriteFinish: { stabilityThreshold: 150, pollInterval: 25 }Note: Providing a custom ignored property in your chokidarConfig is unsupported and will be deleted by the internal watcher logic to allow Eleventy to manage its own ignore patterns.
// Example of how chokidarConfig might be structured in your user config
module.exports = {
chokidarConfig: {
usePolling: true,
interval: 100
}
};The project uses a flat configuration format for ESLint. It is composed of several named configuration blocks that establish a baseline for JavaScript development, project-specific rules, test file handling, and Prettier integration.
Key configuration blocks include:
11ty/setup/js: Uses @eslint/js recommended settings.11ty/rules/project-specific: Configures Node.js globals, ECMAScript module support, and specific stylistic and logic rules.11ty/ignores: Specifically targets test files to relax certain rules like no-unused-vars.11ty/setup/prettier: Integrates eslint-config-prettier to ensure compatibility with Prettier.You can explicitly control how modules are loaded using the loader option in the constructor. This is useful if you want to bypass the automatic detection from package.json.
Supported values:
'esm': Forces ECMAScript Modules.'cjs': Forces CommonJS.'auto': Automatically detects based on package.json (or defaults to ESM in Deno environments).const eleventy = new CoreMinimal({ options: { loader: 'esm' } });The @11ty/client package provides specific entry points for different template engines and plugins via sub-exports. You can import these directly to use specific functionalities in your browser-side code:
@11ty/client: The core client package.@11ty/client/md: Markdown Template Engine.@11ty/client/njk: Nunjucks Template Engine.@11ty/client/liquid: Liquid Template Engine.@11ty/client/i18n: i18n Plugin.