Table of Contents

Concept overview

Baseline makes the structural decisions Eleventy leaves open and wires them into a small set of feature modules that work together. This page is the mental model: what Baseline handles, what stays yours, and how you configure it.

The one-sentence model

Baseline makes the setup decisions (directory structure, template engine, image formats, meta tags, asset bundling, sitemap) so you can skip the wiring and start building.

What Baseline handles, what you handle

Baseline handles

Directory structure: src/ as input, dist/ as output, with a standard layout for assets, data, and templates.
The asset pipeline: PostCSS for CSS, esbuild for JS. One entry point per directory.
Image handling: an image shortcode wired on top of eleventy-img (AVIF and WebP, responsive widths, lazy loading).
The <head> tags: charset, viewport, title, description, robots, canonical, hreflang. You drop a <baseline-head> placeholder in your layout and the plugin fills it.
Sitemaps: XML generation, with per-language sitemaps plus an index when multilang is on.
Debug tooling: globals and filters for inspecting template data, plus an optional virtual page in development.

You handle

Visual design, CSS, layout.
Content structure and naming.
Templates and layout logic.
Deployment.

What that looks like on disk is the annotated tree at the end of this page.

Two configuration surfaces

Baseline's configuration has two parts, and they do different jobs.

1. The plugin call. baseline(settings, options) takes two arguments:

settings is your site identity: title, tagline, url, default language, the language map, and any extra head data you want available to templates.
options is runtime behaviour: which optional modules are on, how verbose the build logs are, and fine-grained module options like head.titleSeparator or assets.esbuild.

import baseline from '@apleasantview/eleventy-plugin-baseline';

const settings = {
	title: 'My Site',
	url: 'https://www.example.com/',
	defaultLanguage: 'en'
};

eleventyConfig.addPlugin(
	baseline(settings, {
		multilingual: false,
		sitemap: true,
		navigator: true
	})
);

The full option list is on the plugin entry point reference; the settings shape is on the site settings reference.

2. The re-exported config. Baseline ships an Eleventy directory configuration alongside the plugin and asks you to re-export it from your eleventy.config.js:

import baseline, { config as baselineConfig } from '@apleasantview/eleventy-plugin-baseline';

export const config = baselineConfig;

Eleventy reads the directory configuration before any plugin runs, so the plugin cannot set it for you from inside addPlugin(). Re-exporting config is how both pieces agree on where things live (src/ as input, dist/ as output, assets and public as virtual asset directories). The full explanation is on the configuration export reference.

The plugin call controls what Baseline does. The config export controls where Eleventy looks. They stay separate because Eleventy needs the directory shape before plugins exist.

The `<head>` placeholder

Most of what Baseline does is invisible: it runs during the build, writes to dist/, and you never see the wiring. There is one visible piece you place by hand, the placeholder.

You drop <baseline-head> in place of the <head> element in a base layout:

<html lang="en">
	<baseline-head></baseline-head>
	<body>
		...
	</body>
</html>

At transform-time (the moment a rendered template is about to be written to disk), the head module replaces the placeholder with a full <head> element containing the resolved tags for the current page. That is the seam between Baseline's automation and your own templates: everything else is configuration; the placeholder is the one thing you place yourself.

See the head module page for the full pipeline.

Where to go next

The project structure for the minimum working configuration.
The content organisation strategy.
The architecture snapshot for the deeper model behind the plugin: state, runtime, modules.
The simple-site tutorial for a guided walk through the same configuration with reasoning.

Previous: Concept

Next: Project structure