AGENTS.md — Whalen Solutions site

AI agent guidance for this repository. Covers build commands, project conventions, and things to know before making changes.

Stack

  • Framework: Jekyll with the Minimal Mistakes remote theme, pinned in _config.yml (remote_theme: mmistakes/minimal-mistakes@<version>)
  • Hosting: GitHub Pages (native Jekyll build — no Actions workflow needed)
  • Contact form: Formspree (see _pages/contact.md)
  • CSS customization: _sass/minimal-mistakes/skins/_whalen.scss

Build commands

# Install dependencies (first time or after Gemfile changes)
bundle install

# Local preview with live reload
bundle exec jekyll serve --livereload

# One-shot build into _site/
bundle exec jekyll build

The site is also built automatically by GitHub Pages on every push to main.

Repository layout

├── _config.yml              ← Main site configuration
├── _data/
│   └── navigation.yml       ← Top nav links — edit this to add nav items
├── _pages/
│   ├── contact.md           ← Contact page (Formspree-backed form)
│   └── thank-you.md         ← Post-submission redirect target
├── _sass/
│   └── minimal-mistakes/
│       └── skins/
│           └── _whalen.scss ← Brand color overrides (do not edit theme files)
├── assets/
│   └── images/              ← Static images; logo PNGs live here
├── index.md                 ← Home splash page (layout: splash)
├── Gemfile                  ← Ruby gem dependencies for local dev
├── AGENTS.md                ← This file
└── CLAUDE.md                ← Claude-specific pointer (references this file)

Brand palette

These values must be used consistently in any SCSS or inline style changes:

Token Hex Usage
Navy dark #0D1929 Masthead, footer background, body text
Teal primary #00C8AA Links, buttons, focus rings, accents
Dark teal #006B5E Hover states
Light blue #E8F4FC Text on dark backgrounds
Mid navy #1B3F6E Borders, secondary elements

All color customizations belong in _whalen.scss. Do not edit theme files directly — the remote theme approach means local overrides survive upgrades.

Adding a page

  1. Create _pages/your-page.md with this front matter:

    ---
layout: single
title: "Page Title"
permalink: /your-page/
---

  2. Add an entry to _data/navigation.yml if it should appear in the nav.

Adding a blog post

  1. Create _posts/YYYY-MM-DD-slug.md with layout: single front matter.
  2. Add a “Blog” link to _data/navigation.yml pointing at /blog/ (or wherever you configure the archive).
  3. The post defaults in _config.yml (date, read time, taxonomy display) are already wired up.

Upgrading Minimal Mistakes

  1. Check the release notes for breaking changes between the current pin and the target version.
  2. Update the version string in _config.yml (remote_theme: mmistakes/minimal-mistakes@X.Y.Z).
  3. Check whether any icon class names have changed (Font Awesome version bumps appear occasionally in MM releases). Footer icon classes live in _config.yml.
  4. Test locally with bundle exec jekyll serve before pushing.

Formspree

The contact form in _pages/contact.md posts to Formspree. The form ID in the action attribute (https://formspree.io/f/YOUR_FORM_ID) must be replaced with a real ID from the Formspree dashboard before the form will work. The free tier allows 50 submissions/month.

Things to avoid

  • Avoid modifying core files under _layouts/, _includes/, assets/css/, or assets/js/ — local copies shadow the remote theme permanently, making upgrades painful. The exception is files Minimal Mistakes provides specifically for user customization (e.g., _includes/head/custom.html, _includes/footer/custom.html). These are safe to override and are unlikely to change between releases.
  • Do not commit _site/ or .jekyll-cache/ — both are in .gitignore.
  • The assets/images/ directory does not belong to the theme; additions here are safe and will not be overwritten by theme upgrades.