Stack Snapshot
- Static site generator: Jekyll 4.x using
pages-themes/cayman@v0.2.0. - Primary build command:
bundle exec jekyll build(serve locally viabundle exec jekyll serve). - Output directory:
_site/→ deployed to Netlify. - Key directories:
_includes,_layouts,_pluginsfor 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
_redirectsat repo root. - Netlify Functions:
verify-recaptchaused 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-recaptchaand Netlify UI deploy logs; document any required fixes inSETUP_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:
#157878plus light neutrals for backgrounds. - Banner images live under
/assets/banners/resized/with naming[topic]-blog.jpgetc. - 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.mdandnetlify.tomlcomments. - Do fail builds when GA4 tokens, Formspree IDs, or Giscus keys are missing—emit descriptive errors instead of silent fallbacks.
- Do keep
_redirectssorted and grouped by section to prevent merge conflicts. - Don’t inject secrets directly into
_layoutsor inline scripts—always rely on theinject-envNetlify 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).