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

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.
  • 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.