Eleventy 3 powers the site; templates live in _includes/ and posts reside in posts/YYYY/*.html with YAML front matter. Shared data sits in _data/, and raw assets go to public/ for pass-through copying. Eleventy writes _site/ on build—treat it as disposable output—while helper scripts like _copyfiles.js and push2live.sh stay in the repo root.
Run npm install once for dependencies. npm run start serves Eleventy with live reload at http://localhost:8080. npm run build produces the static site in _site/; run it before committing or deploying. npm run deploy and npm run all execute server-side workflows—use them only when you intend to push live.
Write content in HTML or Nunjucks, keep filenames kebab-case within the correct year folder, and prefer semantic markup. Indent with two spaces and break long attribute lists onto new lines for readability. Front matter stays double-quoted with ISO-8601 datetimes (e.g. "2023-07-24T10:49"); reuse Eleventy filters and shortcodes instead of inline logic.
There is no automated test suite, so Eleventy build output is the main safety net. Always run npm run build before opening a PR, and use npm run start to spot-check templates or _data changes. Share generated _site/ pages or screenshots when content changes warrant reviewer context.
Commit messages stay short, present-tense, and lower-case (removed html minifier, new links). Keep each commit focused, and document any side effects from script or config updates. Pull requests should summarise scope, link related issues, note build results, and include screenshots for visual changes.
Use docker-compose.local.yml for local overrides and keep secrets in environment variables. Scripts like push2live.sh assume SSH deployment; parameterise hosts instead of hardcoding credentials. Store downloadable assets in public/ so drafts remain outside the published tree.