Stack Snapshot

• Static site generator: Jekyll 4.x using pages-themes/cayman@v0.2.0.
• Primary build command: bundle exec jekyll build (serve locally via bundle exec jekyll serve).
• Output directory: _site/ → deployed to Netlify.
• Key directories:
  • _includes, _layouts, _plugins for custom logic.
  • assets/ for images, diagrams, JS, CSS.
  • netlify-plugins/inject-env/ to expose env vars post-build.

Hosting & CI/CD

• Netlify handles deployments; environment variables live in the Netlify dashboard (never committed).
• Required env vars: RECAPTCHA_SITE_KEY, RECAPTCHA_SECRET_KEY, Formspree endpoint, analytics IDs.
• Redirects managed through _redirects at repo root.
• Netlify Functions: verify-recaptcha used by the contact form to verify tokens and forward to Formspree.

Deploy & Verify Commands

• Local smoke test:

  bundle exec jekyll serve --livereload
  

• Automation sanity check (renders diagrams, GitHub URLs, compiled markdown, snippets):

  npm run ci:all
  

• Netlify function test:

  npx netlify dev --functions=netlify/functions
  

• After deploy, confirm logs via netlify functions:tail verify-recaptcha and Netlify UI deploy logs; document any required fixes in SETUP_GUIDE.md.

Client-Side Expectations

• JavaScript intercepts the contact form submit, triggers reCAPTCHA v3, hits the Netlify function, and surfaces inline status messaging.
• GA4 event tracking for scroll depth, outbound links, CTA clicks, newsletter submission, and errors.
• Comments powered by Giscus — ensure repository IDs remain correct in _config.yml.

Visual System

• Brand color: #157878 plus light neutrals for backgrounds.
• Banner images live under /assets/banners/resized/ with naming [topic]-blog.jpg etc.
• Buttons and interactive elements share consistent styling (rounded corners, pointer cursor, accessible contrast).

Common Pitfalls

• Remote themes sometimes block custom plugins; rely on Netlify build plugins for env injection instead.
• reCAPTCHA hiccups usually come from missing secrets — log errors in the Netlify function and show fallback contact methods.
• Large diagrams/images must be optimized before commit; prefer SVG for diagrams, WebP/JPEG for hero images.

Do / Don’t

• Do document every new environment variable in SETUP_GUIDE.md and netlify.toml comments.
• Do fail builds when GA4 tokens, Formspree IDs, or Giscus keys are missing—emit descriptive errors instead of silent fallbacks.
• Do keep _redirects sorted and grouped by section to prevent merge conflicts.
• Don’t inject secrets directly into _layouts or inline scripts—always rely on the inject-env Netlify plugin.
• Don’t bypass npm run ci:all; it ensures diagrams/snippets stay synchronized with automation.
• Don’t merge banner images over 400 KB; compress first using repo-approved tooling (tools/resize_images.sh).