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

• 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.
• 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