CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# Install dependencies
bundle install

# Run locally (available at http://localhost:4000)
bundle exec jekyll serve

# Build site
bundle exec jekyll build

# Validate spec taxonomy (required before committing _specs/ changes)
ruby scripts/validate_spec_taxonomy.rb

Architecture

Jekyll static site hosted on GitHub Pages. No build pipeline beyond Jekyll itself.

Key directories

  • _specs/{make}/{model}/{year}-{engine}.md — Jekyll collection: vehicle oil specification data (front matter-heavy)
  • specs/{make}/index.html — Make index pages (layout: make_index)
  • specs/{make}/{model}/index.html — Model index pages (layout: model_index)
  • _posts/ — Blog articles
  • _layouts/ — default, post, vehicle-spec, make_index, model_index
  • _includes/ — Reusable HTML snippets
  • scripts/validate_spec_taxonomy.rb — Validates that spec file paths match front matter make/model fields and that corresponding index files exist

Specs collection

Every spec file in _specs/ must have a corresponding make index at specs/{make}/index.html and model index at specs/{make}/{model}/index.html. The directory names must be the slugified version of the make and model front matter values (lowercase, spaces → hyphens). The validation script enforces this.

When adding a new make or model, create the index files first, then add specs.

SEO requirements (hard rules)

  • Every .md / .html file must include layout, title (≤60 chars), description (≤155 chars), last_modified_at, and permalink in front matter
  • Permalinks must use trailing slashes (e.g., /specs/honda/civic/) — never .html extensions
  • Core content must render without JavaScript
  • New images must be WebP with explicit width and height attributes

Vehicle spec front matter

Required fields: layout: vehicle-spec, make, model, year, engine, viscosity, api_rating, capacity_with_filter, capacity_without_filter, capacity_unit, normal_interval, oil_filter_oem, drain_plug_torque, approved_oils, verified, verified_date, verified_source.

See .agent/workflows/create-vehicle-spec-page.md for the full template and workflow.

CI

GitHub Actions runs validate_spec_taxonomy.rb on PRs and pushes to main when _specs/ or specs/ files change.