head

The configuration surface for metadata, theming, performance, and social sharing.

Description

The <head> element is VB's configuration surface. It controls document metadata, theming, performance hints, social sharing, and service worker opt-in. VB's partials/head.njk template generates the full <head> from frontmatter variables, so most pages only need to set title, description, and optionally image in their YAML front matter.

Basic Example

Minimal

Typical VB Page

The partials/head.njk template generates this structure automatically:

<link rel="icon" type="image/svg+xml" href="/favicon.svg">
  <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png">
  <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">

<title>Page Title | Site Name</title>
  <meta name="description" content="A short description of this page.">
  <link rel="canonical" href="https://example.com/page/">

<meta property="og:type" content="website">
  <meta property="og:url" content="https://example.com/page/">
  <meta property="og:title" content="Page Title | Site Name">
  <meta property="og:description" content="A short description of this page.">
  <meta property="og:image" content="https://example.com/og-image.png">

<meta property="twitter:card" content="summary_large_image">
  <meta property="twitter:url" content="https://example.com/page/">
  <meta property="twitter:title" content="Page Title | Site Name">
  <meta property="twitter:description" content="A short description of this page.">
  <meta property="twitter:image" content="https://example.com/og-image.png">

<script>/* ... inline script ... */</script>

<link rel="preconnect" href="https://fonts.googleapis.com" crossorigin>

<link rel="stylesheet" href="/cdn/vanilla-breeze.css">

<meta name="vb-service-worker" content="true">
</head>

Required Elements

Every VB page must include these elements. The head partial handles all of them automatically.

Element	Purpose
`<meta charset="UTF-8">`	Character encoding. Must appear within the first 1024 bytes of the document.
`<meta name="viewport" ...>`	Viewport configuration for responsive layout. VB sets `width=device-width, initial-scale=1.0`.
`<meta name="color-scheme" content="light dark">`	Tells the browser the page supports both color schemes before CSS loads. Prevents a white flash for dark-mode users and enables correct form control styling.
`<title>`	Page title. VB concatenates as `Page Title \| Site Name`, or just the site name if no page title is set.
`<meta name="description">`	Page description for search engines and social previews. Set via the `description` frontmatter field.

Favicon Strategy

VB uses a three-tier favicon approach for maximum browser coverage:

File	Purpose
`favicon.svg`	Primary. Scales perfectly, supports `prefers-color-scheme` media queries for dark-mode favicons.
`favicon-32x32.png`	Fallback for browsers that don't support SVG favicons (older Safari, some RSS readers).
`apple-touch-icon.png`	180×180 PNG used when iOS users add the site to their home screen.

Social Metadata

VB generates Open Graph and Twitter Card tags automatically from frontmatter.

Open Graph

Twitter Card

Custom OG Image

Override the default /og-image.png with the image frontmatter field:

Canonical URL

VB auto-generates a canonical URL from site.url + page.url. This tells search engines the preferred URL for each page, preventing duplicate content issues.

Theme Flash Prevention

An inline <script> runs before CSS loads to prevent a flash of wrong theme. It reads the user's saved preferences from localStorage and applies data attributes to <html> synchronously:

Preference	Storage Key	Attribute Set
Light/dark mode	`vb-theme` → `.mode`	`data-mode`
Brand theme	`vb-theme` → `.brand`	`data-theme`
Accessibility themes	`vb-a11y-themes`	`data-theme`
Fluid scaling preset	`vb-theme` → `.fluid`	`data-fluid`
Reduced motion	`vb-extensions` → `.motionFx`	`data-motion-reduced`
Browser chrome color	(derived from mode)	`<meta name="theme-color">`

The script also updates the theme-color meta tag so the browser chrome matches the applied mode rather than the OS preference.

// Apply mode before CSS loads
    if (mode !== 'auto') {
      document.documentElement.dataset.mode = mode;
    } else if (matchMedia('(prefers-color-scheme: dark)').matches) {
      document.documentElement.dataset.mode = 'dark';
    }

// Compose theme: brand + accessibility layers
    const a11y = JSON.parse(localStorage.getItem('vb-a11y-themes') || '[]');
    const parts = [];
    if (brand && brand !== 'default') parts.push(brand);
    parts.push(...a11y);
    if (parts.length) document.documentElement.dataset.theme = parts.join(' ');

// Fluid scaling preset
    if (stored.fluid) document.documentElement.dataset.fluid = stored.fluid;

// Update theme-color meta to match applied mode
    const effective = mode !== 'auto' ? mode
      : matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
    const color = effective === 'dark' ? '#1a1a1a' : '#ffffff';
    document.querySelectorAll('meta[name="theme-color"]').forEach(m => {
      m.removeAttribute('media');
    });
    document.querySelector('meta[name="theme-color"]').content = color;

// Reduced motion preference
    const ext = JSON.parse(localStorage.getItem('vb-extensions') || '{}');
    if (ext.motionFx === false) {
      document.documentElement.dataset.motionReduced = '';
    }
  } catch(e) {}
</script>

Performance

Preconnect

VB preconnects to Google Fonts so the DNS lookup, TCP handshake, and TLS negotiation happen in parallel with CSS parsing:

Theme Color

Two <meta name="theme-color"> tags tell the browser what color to paint the address bar and tab strip, matched to VB's default backgrounds:

The theme flash prevention script dynamically updates these to match the user's chosen mode, so the browser chrome stays in sync even when the mode is explicitly set (not following OS preference).

CSS Loading

VB uses different CSS paths in development and production:

The site.css data variable handles this automatically — /src/main.css in dev mode (served by Caddy), /cdn/vanilla-breeze.css in production.

Service Worker

VB's service worker is opt-in. Add the meta tag to enable offline caching and background updates:

Alternatively, set the flag in JavaScript before VB's autoloader runs:

When enabled, VB registers a service worker that caches CSS, JS, and font assets using a stale-while-revalidate strategy. See the Performance page for details on cache strategies and lifecycle.

Extension Point

Child layouts can inject additional content into <head> using the extraHead block. This is the recommended way to add page-specific styles, fonts, or scripts:

The block appears after all standard head content, so page-specific styles can override defaults without specificity battles.

Permitted Child Elements

The <head> element may only contain metadata content:

Element	Purpose
`<title>`	Document title (exactly one required)
`<meta>`	Metadata: charset, viewport, description, theme-color, etc.
`<link>`	External resources: stylesheets, favicons, preconnects, canonical URLs
`<style>`	Inline CSS (prefer external stylesheets; use for critical CSS or page-specific overrides)
`<script>`	JavaScript (VB uses this for theme flash prevention)
`<base>`	Base URL for relative links (rarely needed)
`<noscript>`	Fallback content when JavaScript is disabled

Accessibility

lang on <html>: Set on the parent <html> element (not <head>), this attribute tells screen readers which pronunciation rules to use. VB's base layout sets lang="en" by default.
description meta: Provides a concise page summary for search engines and assistive technology. Screen readers can announce this to help users decide whether to continue reading.
color-scheme meta: Informs the browser about supported color schemes before CSS loads. This is essential for forced-colors mode and ensures native form controls (inputs, selects, textareas) render in the correct scheme from the first paint.
Title pattern: The Page Title | Site Name format gives screen reader users immediate context about both the specific page and the site they're on.

<html> - Root element with theming and layout attributes
<body> - Document content container
<title> - Document title element
<meta> - Metadata element
<link> - External resource link
Themes - Full theme catalogue with live previews
Fluid Scaling - How data-fluid presets work
Design Tokens - Color, spacing, and typography tokens
Performance - Caching strategies and service worker details

Welcome to Vanilla Breeze