English  Nederlands  Français  Toggle theme

Eleventy Baseline

Start building your site, skip the recurring setup work.
Table of Contents

Overview

What Baseline is

Baseline is an Eleventy plugin that handles the scaffolding every Eleventy site ends up needing.

Eleventy hands you a content pipeline and gets out of your way. That is the appeal, and also the reason every site you build with it ends up needing the same wiring underneath: directory layout, an asset pipeline, image handling, head tags, sitemap, language routing.

None of it is hard. You just write it again every time. The usual ways out are starter repos that fork once and rot, or stacks of single-purpose plugins that do not know about each other and tend to fight at the edges.

Baseline handles the infrastructure layer, specifically the parts that fit together. The plugin is shaped in three layers:

  • State is your settings and options, normalised once at startup.
  • Runtime: state in motion, plus a per-page context and a registry that lets the modules read what they need without reaching across to each other.
  • Modules are the five feature plugins, self-contained slices of behaviour backed by the runtime.

Your layouts in _includes/, your content and data in content/ and _data/, your styles and scripts in assets/, and any plugins or filters you add yourself, all stay yours.

Who this is for

Baseline is written for someone who has built a handful of Eleventy sites and caught themselves wiring up the same things every time. You want those decisions made together, so they fit. You still want to own your templates, content, and design. You would rather start from a working Baseline than a blank slate, or a starter repo that forks once and goes stale.

It is probably not for you if you already have a setup you like. Baseline does not replace what works; it replaces the third or fourth time you would set the same thing up from scratch. It is also not for you if you want a full framework that owns layout and content as well. Baseline is deliberately smaller than that.

Why a plugin?

Recipes drift. Starter repos fork once and rot. Frameworks impose more than they solve. Instead of hunting through six tutorials and reconciling them by hand each time if Eleventy defaults changes or patterns shift, you get the new version of Baseline on npm install.

What the Baseline modules do

Five modules, each wiring a distinct concern into Eleventy:

  • assets: the asset pipeline. One CSS entry point per directory through PostCSS, one JS entry point through esbuild, and inline filters (inlinePostCSS, inlineESbuild) for critical-path CSS or JS.
  • head: a <baseline-head> placeholder that gets replaced with a sorted, deduped element list. Charset, viewport, title, description, robots, canonical, hreflang. You drop the placeholder in your layout once.
  • multilang: directory-based multilingual support. Per-language collections, hreflang, a translation map, and the standard i18n filters (it wraps Eleventy's I18nPlugin). Opt-in.
  • navigator: a debug surface. Globals and filters for inspecting template data, plus an optional virtual page that lists every template the build sees. On in development by default.
  • sitemap: an XML sitemap. Every page is included unless you exclude it. When multilang is active, you get per-language sitemaps plus an index.

Threading the modules together is page context at _pageContext: a normalised per-page object the head, multilang, and sitemap modules all read from internally. Your templates can read it too. It is what lets the modules cooperate without each one having to know about the others. See the page context reference.

Baseline additions

Alongside the modules, Baseline registers a small set of additions the moment you load it. These are always on because they are too small to be worth opting in or out of:

  • Filters: markdownify, relatedPosts, isString. See the filters reference.
  • Globals: a date-formatting helper, plus the _baseline data tree (env, features, paths) that templates can read at any time. See the globals reference.
  • An image shortcode built on top of eleventy-img: AVIF and WebP, responsive widths, lazy loading. Alt text is required; the build warns if you skip it.

And three behaviours that need no configuration at all:

  • A drafts preprocessor: any template with draft: true in front matter is excluded from production builds.
  • A dev image pipeline: eleventy-img is wired up for in-flight transforms during --serve.
  • Passthrough copy for the static/ directory: anything in there is copied to the site root as-is.

The full surface lives in the [[reference | reference]] chapter.

Stability and scope

Baseline is in active development. Versions ship as 0.1.0-next.X and that is a deliberate signal: things may shift between releases, and you should pin a version when you build something serious on top. The five modules above are the supported surface today. Open Graph and Twitter cards are staged in the code but not wired through to output yet; if you need them now, render them yourself via settings.head.meta[].

If something in the docs claims a behaviour you cannot reproduce, the docs are probably wrong. Please open an issue.

Where to go next

  • The concept chapter for the mental model and community-seeded conventions.
  • The quickstart for a checklist that gets you a running site.
  • The simple-site tutorial for a guided walk through the same checklist with reasoning.
  • The architecture snapshot for a deeper look at the three layers if you want it.

Already have an Eleventy site you want to graft Baseline onto? See Integrate with Eleventy Base Blog.

Previous: Introduction

Next: Quickstart