--- title: 'How Baseline works' description: 'A conceptual map of Baseline: what it handles, the placeholder, and the two configuration surfaces.' slug: 'how-baseline-works' type: 'article' date: 2026-04-28T00:00:00.000Z lang: 'en' url: 'https://www.eleventy-baseline.dev/docs/concept/how-baseline-works/' --- 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 `` tags: charset, viewport, title, description, robots, canonical, hreflang. You drop a `` 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 on [[project-structure | project structure]]. --- ## Two configuration surfaces Baseline's configuration has two parts, and they do different jobs. **The plugin call**, `baseline(settings, options)`, controls what Baseline does. Two arguments, and the split between them is the thing to hold onto: {% stepsBlock "compact" %} - `settings` is your **site identity**: title, tagline, url, default language, the language map, and any extra head data. The things that would still be true if you rewrote every template tomorrow. - `options` is **runtime behaviour**: which optional modules are on, how verbose the build logs are, and fine-grained module options. {% endstepsBlock %} Keeping them apart means you can rename your site without going near the module configuration, and switch a module off without touching your site's identity. **The re-exported `config`** controls where Eleventy looks. Baseline ships a directory configuration alongside the plugin and asks you to forward it, because Eleventy reads that configuration before any plugin exists and no plugin can set it from inside `addPlugin()`. They stay separate for that reason alone: one is a decision Baseline can make at plugin time, the other is a decision Eleventy has already made by then. The option list is on the [[plugin-entrypoint | plugin entry point reference]], the settings shape on [[site-settings | site settings]], and the directory contract on [[config-export | config export]]. --- ## The `` 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 `` in place of the `` element in a base layout: ```html ... ``` Baseline replaces that element with a full `` on the way to disk. The placeholder _is_ the head, not a tag inside it, which is why it sits as a sibling of ``. 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 | head module]] for what it emits and when. --- ## Where to go next - The [[project-structure | project structure]] for the rules those decisions turn into on disk. - The [[content-organisation | content organisation]] strategy. - The [[architecture-snapshot | architecture snapshot]] for the deeper model behind the plugin: state, runtime, modules.