Eleventy Plugin Baseline

A magic carpet ride

Table of Contents

head-core

Note: The options API is still evolving; expect tweaks as the project grows.

What it does

  • Injects head elements via PostHTML using a <baseline-head> tag.
  • Builds head data from site/page/front matter and _data/head.js with one shared builder (used in both eleventyComputed and the HTML transform).
  • Handles canonical (absolute when site.url or siteUrl/env URL is set), robots, OG/Twitter shells, and link/script.
  • Adds eleventyComputed.page.head to supply merged head data per page.

Defaults

  • Head tag: <baseline-head>.
  • User data key: head (via dirKey default).
  • EOL: \n.
  • Verbose follows Baseline verbose (or per-module option).

Options

  • verbose (boolean): extra logging (defaults to Baseline verbose). Other head-core options are internal for now.
  • Peer deps: none (uses PostHTML bundled with Eleventy).

How it works

  • Listens to eleventy.contentMap to cache inputPath↔url maps (for canonical resolution).
  • Adds eleventyComputed.page.head, which calls the shared buildHead (site + user + page merge).
  • Adds a PostHTML plugin that also calls buildHead (or reuses page.head when present) to transform <baseline-head> into head elements.
  • Canonical prefers head.canonical, then page.url/content map, absolutized with site.url/siteUrl/env URL + pathPrefix.
  • Flattens and dedupes meta, injects canonical link, preserves element order: base meta, title, links/scripts, then OG/Twitter meta.

Tips

  • <baseline-head> must exist inside <head>; if it’s missing or moved, no head elements will be injected.
  • Set global defaults in _data/head.js; override per page with head: in front matter.
  • To get absolute canonical/og:url, set site.url in your data (or pass siteUrl option, or use URL/DEPLOY_URL env vars).
  • Provide canonical, description, and social image at page level when you have them; otherwise defaults apply.
  • noindex: true in front matter is used to emit robots meta (noindex, nofollow).
  • If you pass a string path for headElements, it is loaded via require() at build time. Only use trusted, local paths; prefer passing an object.
  • See the “Head & SEO Basics” tutorial for a guided setup; pair with the deployment URL hygiene and social previews tutorials for correct URLs and images.
  • Tutorial: Head & SEO Basics
  • Related: Deployment URL Checks, Custom Social Previews

Previous: assets-postcss

Next: multilang-core