Plugin entrypoint

The baseline() factory is the single entry point. You call it once in your Eleventy config callback with two arguments: site settings and module options. Everything below is what that call sets up.

For the directory contract Baseline ships alongside the factory, see Config export. For the settings argument, see Site settings. This page covers the second argument, options, which controls module activation and behaviour.

Default usage

import baseline, { config as baselineConfig } from '@apleasantview/eleventy-plugin-baseline';
import settings from './src/_data/settings.js';

/** @param {import("@11ty/eleventy").UserConfig} eleventyConfig */
export default async function (eleventyConfig) {
	await eleventyConfig.addPlugin(baseline(settings));
}

export const config = baselineConfig;

baseline() itself is synchronous, but it returns an async closure (Eleventy's documented async-plugin pattern). The await on addPlugin is the correct shape.

Options

await eleventyConfig.addPlugin(
	baseline(settings, {
		verbose: false,
		multilingual: false,
		sitemap: true,
		navigator: true,
		head: { titleSeparator: ' – ', showGenerator: false },
		assets: { esbuild: {} },
		media: { image: { widths: [320, 640, 960, 1280, 1920], formats: ['avif', 'webp', 'jpeg'] } }
	})
);

Option keys are checked structurally at startup and mismatches are warned about, not thrown. media is checked strictly, so a misspelled key there is named rather than ignored: options: media.image, Unrecognized key: "width".

The three states of verbose

Saying nothing and saying false are different requests, so the option has three settings rather than two.

Leave it unset and you get the boxed startup banner, a "Baseline vX, running Eleventy vY" line, and one line naming the active modules. Set it to true for the full narrative on top of that. Set it to false and Baseline says nothing at all.

Eleventy's own --quiet has the same effect as false, so a quiet build is quiet throughout. warn and error emit in every state: a silent build still surfaces problems.

What Baseline registers

In the order the entry point runs:

Steps 10, 15 and 16 are the guarded ones: a preprocessor, filter or shortcode name you have already defined stays yours, and the build prints one line naming what it skipped. See Who owns a name for why that works wherever you wrote it.

The head module's render strategy is selected by a code-level driver seam, not a user option. One driver ships today. See Internals.

Who owns a name

Baseline yields: a filter, shortcode or preprocessor you have already defined stays yours, and the build prints one line naming what it skipped. Two Eleventy behaviours sit underneath that and are worth knowing when it does not go the way you expect.

Your config finishes before any plugin body runs. addFilter and addShortcode take effect where you write them; addPlugin queues, and the queue does not start until your config callback has returned. So a name you register directly is already in place when Baseline executes, which is exactly why Baseline can see it and stand down, whether you registered it above or below the addPlugin call. Order within your own file does not matter here.

Registering from inside another plugin is the case that does behave by order, because plugin bodies run in the order they were added. If you need your registration to land after Baseline's, add it as a plugin of your own, after Baseline.

Overwriting is invisible by default. Eleventy does warn when a filter or shortcode is redefined, but through debug, so nothing appears on a normal build. To see it:

DEBUG=Eleventy:UserConfig npx @11ty/eleventy

Collections behave the other way and throw outright on a duplicate name, so the two adjacent APIs fail in opposite directions.

Plugin metadata

baseline() returns a function whose name property is set to @apleasantview/eleventy-plugin-baseline, so eleventyConfig.hasPlugin('@apleasantview/eleventy-plugin-baseline') returns true once the plugin is added.

Not included

@11ty/eleventy-img's HTML transform (eleventyImageTransformPlugin) is not bundled. Add it yourself if you want content-level <img> rewrites. The image shortcode works either way; the difference is whether <img> tags written into Markdown also get transformed.

See also

• Site settings - the settings argument.
• Config export - the directory contract.
• Globals - _baseline, _pageContext, _snapshot, and the reserved keys.
• Page context - what the registry exposes.
• Internals - registry, stores, virtual dirs, driver seam.