Eleventy notes theme

Shared Eleventy (3.x) base theme: layouts, CSS, client-side JS, webfonts, and an Eleventy plugin that wires them into a consuming site. Multiple sites can depend on this package, override any template or design token, and add their own templates and styles alongside it.

Installing

The theme is consumed straight from this repository as a git dependency (no npm publishing required):

"dependencies": {
  "@src-dev/eleventy-notes-theme": "github:stephen-cox/eleventy-notes-theme#semver:^0.1"
}

Tag releases in this repository (v0.1.0, …) and each site upgrades deliberately with npm update — a theme change never reaches a site until the site takes it, and the site's visual regression tests vet the upgrade.

Usage

const notesTheme = require('@src-dev/eleventy-notes-theme');

module.exports = function (eleventyConfig) {
  eleventyConfig.addPlugin(notesTheme, {
    // Glob for the site's Markdown content, used by the `pages` collection.
    contentGlob: './src/**/*.md',   // default
  });
};

The plugin registers:

• Layouts — base.njk and page.njk as virtual templates in the site's includes directory, for front matter layout: references.
• Template lookup — a Nunjucks loader that searches the site's includes directory first and the theme's layouts/ second, for {% extends %} / {% include %} / {% import %}.
• Includes and macros — includes/header.njk, includes/footer.njk, macros/breadcrumb.njk, macros/card.njk.
• Filters — formatDate, trim; shortcodes — socialImage, year.
• Collections — pages, noIndex.
• Libraries — the configured markdown-it instance, and @11ty/eleventy-navigation.
• Global data — environment (from ELEVENTY_ENV).
• Fonts — passthrough-copied to /_assets/fonts/.

Overriding templates

Create a file with the same name in the site's includes directory and it wins over the theme's copy — both for front matter layouts and for {% extends %} / {% include %} lookups:

src/_layouts/includes/header.njk   overrides the theme header
src/_layouts/page.njk              overrides the theme page layout

Site-only layouts (e.g. recipe.njk) live in the site as normal and can {% extends "base.njk" %} into the theme.

CSS

Import the whole theme and override design tokens (everything in css/base/variables.css is a custom property):

@import url("@src-dev/eleventy-notes-theme/css/theme.css");

:root {
  --color-accent-1: rebeccapurple;
}

@import url("./components/my-component.css");

Or import the individual files (see css/theme.css for the canonical order) to interleave site styles at exact points in the cascade, as kitchennotes.net does. postcss-import resolves the package name from node_modules.

JS

Client-side modules are plain CommonJS for the site's webpack bundle:

const { cardClick } = require('@src-dev/eleventy-notes-theme/js/card.js');

Site expectations

Theme templates read the site's global data:

• site.title, site.alt_title, site.site_url, site.twitter, and optionally site.gtm_id (Google Tag Manager, production only).
• A favicon passthrough-copied to /_assets/images/favicon.svg.
• The asset pipeline shortcodes assetLink / scriptLink from @src-dev/eleventy-template-asset-pipeline, with collections named _stylesheets and _scripts.

Build-environment helpers (environment, isProduction, isOptimised) are exported from lib/environment.js for the site's build scripts.