AGENTS.md

AGENTS.md

Guidelines for agentic coding tools operating in this repository.

Repo Snapshot

  • Stack: Ruby + Jekyll (GitHub Pages style site).
  • Purpose: static blog from Markdown, Liquid templates, SCSS, and small JS helpers.
  • Ruby version: 3.2.2 (.ruby-version).
  • Main gem set: github-pages, jekyll, jekyll-admin, webrick.

Key Paths

  • _posts/ blog posts.
  • _pages/ static pages.
  • _layouts/ layout shells (default, post, page).
  • _includes/ shared Liquid snippets.
  • _sass/ SCSS partials.
  • assets/ compiled-entry SCSS and JS.
  • _config.yml base config.
  • _config_dev.yml local dev overrides.
  • serve.sh local serve shortcut.

Build, Lint, and Test Commands

Run from repository root.

Install deps

bundle install

./serve.sh

Equivalent:

bundle exec jekyll serve --config _config.yml,_config_dev.yml --livereload

_config_dev.yml is gitignored, so a fresh clone or worktree lacks it and serve.sh fails until you create it (a file containing only url: http://localhost:4000 suffices). Plain bundle exec jekyll build needs only _config.yml.

Build site

bundle exec jekyll build

Clean output

bundle exec jekyll clean

Lint-like diagnostics

bundle exec jekyll doctor

Test Status in This Repo

  • No formal test framework is configured (no RSpec/Minitest test suite).
  • No dedicated linter is configured (no RuboCop config present).
  • Practical validation is build + doctor + focused manual checks.

Suggested validation sequence after edits:

  1. bundle exec jekyll build
  2. bundle exec jekyll doctor
  3. bundle exec jekyll serve --config _config.yml,_config_dev.yml --livereload
  4. Manually verify changed pages/components in browser.

Running a Single Test (Focused Check)

Since there is no unit-test runner, a “single test” means a targeted smoke check.

Useful command:

bundle exec jekyll build --limit_posts 1

How to do focused checks:

  • Post content change: open only the affected post URL and verify rendering.
  • Layout/include change: verify one post page + one page in _pages/.
  • SCSS change: verify desktop and mobile behavior on touched views.
  • JS change: verify the specific interaction and check browser console.

Code Style Guidelines

General

  • Preserve existing Jekyll/Liquid structure.
  • Make minimal, localized changes; avoid broad refactors unless requested.
  • Do not commit generated artifacts (_site/, caches, vendor bundles).
  • Default to ASCII unless file already relies on Unicode.

Markdown and Front Matter

  • Keep valid YAML front matter (--- delimiters).
  • Common keys: layout, title, categories, permalink, use_math.
  • Use layout: post for posts, layout: page for pages.
  • Keep categories consistent with existing taxonomy.
  • Set use_math: true only when math is required.

Naming Conventions

  • Posts use repo convention: _posts/YYYY-M-D-Title.md.
  • CSS selectors: kebab-case.
  • JS identifiers: camelCase.
  • Front matter keys: lowercase snake_case.

Liquid and Includes

  • Reuse _includes/* instead of duplicating template blocks.
  • Keep Liquid logic simple, readable, and close to existing patterns.
  • Keep optional include params guarded with conditionals.

SCSS/CSS

  • Place reusable values in _sass/_variables.scss when appropriate.
  • Keep related styles near existing sections in assets/style.scss or assets/main.scss.
  • Respect existing responsive behavior and verify at small widths.
  • Avoid visual redesigns unless explicitly requested.

JavaScript

  • Repo uses plain browser JS (no TypeScript setup).
  • Match existing style: const/let, single quotes, semicolons.
  • Hook DOM behavior on DOMContentLoaded.
  • Use defensive DOM checks before reading or mutating elements.
  • Prefer fail-soft behavior over throwing runtime errors.

Imports and Dependencies

  • Ruby deps: Gemfile and Gemfile.lock.
  • SCSS imports: existing import flow in assets/style.scss.
  • Add dependencies only when necessary and clearly justified.

Content and Media Conventions

  • Prefer _includes/image.html for figures.
  • After adding or replacing images, run python3 scripts/image_dimensions.py and commit _data/image_dimensions.yml (the include’s width/height source).
  • Always provide meaningful alt text.
  • Keep captions short and relevant.
  • Keep internal URLs consistent with existing site.baseurl usage.

Cursor / Copilot Rules Status

Checked locations for additional agent instructions:

  • .cursorrules
  • .cursor/rules/
  • .github/copilot-instructions.md

Current status: none of these files exist in this repository.

If added later, treat them as higher-priority instructions and update this file.

Maintaining this file

Keep this file for knowledge useful to almost every future agent session in this project. Do not repeat what the codebase already shows; point to the authoritative file or command instead. Prefer rewriting or pruning existing entries over appending new ones. When updating this file, preserve this bar for all agents and keep entries concise.