Eleventy Baseline
English Nederlands Français
|
Table of Contents

Config export

Baseline ships a directory contract as a named export. Eleventy's modules expect specific input, output, includes, and data folders; Baseline's modules expect two more (assets, public).

The export bundles all of that into a single object you re-export from your config file, so you never have to keep both halves in sync.

For the runtime side of the plugin, see Plugin entrypoint.

Why a config export

Eleventy reads its directory layout from the config callback's return value. Baseline reads its own layout (asset pipeline source, public passthrough source) from the same object. Re-exporting baselineConfig is how you give both halves the same shape with one line.

You can also write the object yourself. The export is a convenience, not a requirement; the modules just need certain keys to exist. Starting from baselineConfig is the safe path.

The exported object

export const config = {
	dir: {
		input: 'src',
		output: 'dist',
		data: '_data',
		includes: '_includes',
		assets: 'assets',
		public: 'static'
	},
	htmlTemplateEngine: 'njk',
	markdownTemplateEngine: 'njk',
	templateFormats: ['html', 'njk', 'md']
};

input, output, data, includes are Eleventy's own keys. assets and public are Baseline's; together they make the asset pipeline and the passthrough mount possible.

There is a third key Baseline reads and does not ship a default for, because its default is not a subdirectory of anything: dir.cache, which moves the directory Baseline writes outside your output. It holds the content graph and the image renditions, it defaults to .cache beside your input, and it takes an absolute path if you want it on another disk.

return { ...baselineConfig, dir: { ...baselineConfig.dir, cache: '.cache/baseline' } };

See Persist the build cache for what is in there and what is worth keeping between deploys.

The assets / public asymmetry

Two virtual directories, one with a name that looks unusual on disk:

  • assets - the asset pipeline's source directory. Both the virtual key and the on-disk folder are called assets. CSS, JS, and the like live here and pass through PostCSS/esbuild.
  • public - the passthrough source directory. The virtual key is public, but the on-disk folder is static/. Files placed there are copied verbatim to the site root / at build time.

The on-disk name static/ matches the convention used across most static-site generators (Astro, Next, Hugo, Eleventy starters). The virtual key public matches what 11ty's own ecosystem calls the same idea.

Baseline keeps both: the folder you create on disk reads naturally to anyone arriving from another SSG; the key you reference in eleventyConfig.directories reads naturally inside Eleventy.

If you override dir.public, the on-disk folder changes; the virtual key stays public. If you override dir.assets, both change in lockstep.

See Internals for how the virtual keys are synthesised onto eleventyConfig.directories.

Use as-is

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;

Override safely

Spread baselineConfig first, then override only what you need:

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,
	dir: {
		...baselineConfig.dir,
		output: 'public_html',
		public: 'public'
	},
	templateFormats: [...baselineConfig.templateFormats, 'liquid']
};

A few things worth keeping straight when you override:

  • dir.output - renaming it does not change the passthrough mount. The public directory still copies to the site root /, just under your new output folder.
  • dir.assets - renaming it also renames the URL prefix the asset pipeline writes to. Update your <link> and <script> references accordingly.
  • htmlTemplateEngine and markdownTemplateEngine - leave both at 'njk' unless you have a reason not to. Several of Baseline's virtual templates are Nunjucks, and swapping engines globally turns them off.
  • templateFormats - must include 'njk' for the same reason. Baseline's configSchema says so, but it runs in the plugin's own test suite rather than against your project at build time, so dropping njk fails quietly: the virtual templates stop rendering and nothing tells you why.

Caveats

The defaults are the path Baseline tests against. Non-default template engines (Liquid, Handlebars) and uncommon format combinations have not been thoroughly verified. Override what you need; just expect the well-trodden path to be the trodden one.

See also