J3ZZ

CLAUDE.md

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

Project Overview

This is a Jekyll static site deployed to GitHub Pages at www.j3zz.com. The site is a portfolio website with a custom design inspired by julienbayle.net, featuring a grid-based portfolio system with filterable works.

Key Features:

Quick Start

Local Development

bundle exec jekyll serve

Starts local development server at http://localhost:4000 with auto-regeneration enabled. The server watches for file changes and rebuilds automatically.

Important: Changes to _config.yml require a server restart to take effect.

Build Site

bundle exec jekyll build

Generates the static site in the _site/ directory.

Run Tests

⚠️ IMPORTANT: All testing happens LOCALLY. GitHub Actions only builds and deploys - it does NOT run tests!

Tests run automatically before EVERY commit:

git add .
git commit -m "Your message"  # ← Full tests run here automatically
git push origin main          # ← Push proceeds immediately (tests already passed)

The pre-commit hook automatically runs the complete test suite (./test-before-push.sh) before EVERY commit. This ensures you never commit broken code.

Commits will be blocked if tests fail. Fix the errors, then try committing again.

Optional - Manual testing during development:

./test-before-push.sh

Run this to test your changes before committing. Useful for catching errors early during development.

Individual test commands:

yamllint .

Validates YAML syntax and formatting in all configuration files and workflows. Very fast.

bundle exec rake test

Runs automated tests (html-proofer) to validate links, images, and HTML structure.

npm run lighthouse

Runs Lighthouse CI for performance, accessibility, and SEO validation (requires Chrome/Chromium). Optional but recommended for major releases.

npm run test:print

Runs print tests to validate QR codes, print layouts, and A4 formatting (requires Chrome/Chromium).

Note: Print tests may skip locally in WSL due to Chrome availability, but the pre-push hook handles this gracefully.

Install/Update Dependencies

bundle install

Run after modifying Gemfile or when setting up the project for the first time.

npm install

Installs Node.js dependencies for Lighthouse CI testing and Lefthook git hooks.

bundle update github-pages

Updates GitHub Pages and all associated Jekyll dependencies.

Git Hooks (Lefthook)

This project uses Lefthook to enforce local testing before commits and pushes.

⚠️ CRITICAL: These hooks are your ONLY safety net! GitHub Actions does NOT run tests.

Setup (first time only):

npm install
npx lefthook install

What runs automatically and BLOCKS commits if tests fail:

Tests run before EVERY commit to ensure you never commit broken code. All commits are validated and safe.

Skipping hooks (use with EXTREME caution):

LEFTHOOK=0 git commit -m "message"
# or
git commit --no-verify -m "message"

⚠️ WARNING: Skipping hooks means committing untested code. Only skip if:

Manual hook testing:

npx lefthook run pre-commit
npx lefthook run pre-push

Configuration is in lefthook.yml.

Workflow

New to the project? See Development Workflow for complete step-by-step instructions from making changes to deployment with all necessary commands.

Quick workflow:

  1. Make changes → 2. Preview locally → 3. Commit → 4. Push → 5. Auto-deploy

Documentation Structure

This project’s documentation is organized into topic-specific files for better performance and maintainability:

🚀 Development Workflow

⭐ START HERE - Complete workflow from making changes to deployment.

Read this for:

📐 Architecture

Site structure, navigation system, portfolio configuration, styling, print functionality, SEO, analytics, and deployment details.

Read this for:

📝 Content Management

Front matter standards, adding portfolio works and events, multi-category support.

Read this for:

🧩 Modules Reference

Complete reference for all 11 modular layout components with examples.

Read this for:

🏷️ Metadata Reference

Category-specific metadata templates and field documentation.

Read this for:

✅ Best Practices

Workflows, guidelines, and standards for creating and maintaining portfolio works.

Read this for:

🧪 Testing

Automated testing system to prevent breaking changes during development.

Read this for:

🎓 Testing & Deployment Tutorial

⭐ START HERE - Step-by-step practical guide for testing and deployment.

Read this for:

Common Tasks

Adding a New Portfolio Work

  1. Create file: _portfolio/YYYY-MM-DD-work-slug.md (e.g., 2026-01-01-new-work.md using the actual release/creation date)
  2. Follow the standardized structure from Best Practices
  3. Use category-specific metadata template from Metadata Reference
  4. Combine modules from Modules Reference
  5. Test locally: bundle exec jekyll serve
  6. Verify printable page: /works/

Adding a New Event

  1. Create file: _events/YYYY-MM-DD-event-name.md (e.g., 2025-06-15-festival-performance.md using the actual event date)
  2. Follow event front matter standards from Content Management
  3. Optionally link to a work using work_id field
  4. Test locally and verify display on /events/

Modifying Site Pages

All page files are located in the _pages/ directory.

For detailed information, see Architecture > Modifying Page Content

Updating Site Configuration

Edit _config.yml for:

Remember: Restart Jekyll server after config changes.

See Architecture > Configuration Variables for all available settings.

Configuring Mailchimp Newsletter

The contact page includes a Mailchimp newsletter signup form. To enable it:

  1. Log into Mailchimp
  2. Go to Audience → Signup forms → Embedded forms
  3. Copy the form action URL from <form action="...">
  4. Copy the bot field name from the hidden field (e.g., b_XXXXXXXXXX_XXXXXXXXXX)
  5. Update _config.yml: 
    mailchimp_action_url: "https://XXXX.usX.list-manage.com/subscribe/post?u=XXXXXX&id=XXXXXX"
mailchimp_bot_field: "b_XXXXXXXXXX_XXXXXXXXXX"
  6. Restart Jekyll server

If Mailchimp is not configured, the form will show “Newsletter signup coming soon.”

Configuring SEO

The site includes comprehensive SEO optimization powered by the jekyll-seo-tag plugin with custom enhancements.

SEO Features:

Configuration in _config.yml:

# Basic site info
title: J3ZZ
description: >-
  French sound artist creating experimental electronic music...

# Author information
author:
  name: J3ZZ
  email: hello@j3zz.com
  twitter: j3zz

# Social profiles for SEO
social:
  name: J3ZZ
  links:
    - https://bandcamp.com/iamj3zz
    - https://soundcloud.com/j3zz
    # ... additional social links

# Additional SEO settings
tagline: "Experimental sound art merging music, generative systems, and immersive installations"
default_image: /assets/img/J3ZZ-logo-black-300px.png
lang: en_US

SEO Implementation:

Note: The site automatically generates a sitemap at /sitemap.xml and declares it in robots.txt.

Configuring Google Analytics 4

The site includes privacy-compliant Google Analytics 4 integration that respects GDPR cookie consent preferences.

To enable Google Analytics:

  1. Create a GA4 property in Google Analytics
  2. Copy your Measurement ID (format: G-XXXXXXXXXX)
  3. Update _config.yml: 
    google_analytics: G-XXXXXXXXXX  # Replace with your actual GA4 measurement ID
  4. Restart Jekyll server

Privacy Features:

Implementation:

Note: If google_analytics is not configured in _config.yml, no analytics code is loaded.

The site includes a GDPR-compliant cookie consent system for managing user privacy preferences.

Cookie Categories:

  1. Essential cookies - Always enabled (site functionality, localStorage for preferences)
  2. Analytics cookies - Google Analytics 4 (optional, requires user consent)
  3. Embedded content cookies - Third-party embeds like YouTube, Vimeo, Bandcamp (optional, requires user consent)

User Controls:

Implementation:

Customization: Cookie banner styling can be customized in assets/css/style.css (search for .cookie-consent-banner).

Template Works

Reference these portfolio works for implementation examples:

Testing & Quality Assurance

⚠️ CRITICAL: All testing happens LOCALLY. GitHub Actions does NOT run tests!

The site includes comprehensive automated testing that runs on your machine before pushing:

Tests enforced by Lefthook git hooks:

Required workflow:

  1. Make your changes
  2. Run ./test-before-push.sh (or let Lefthook run it automatically on git push)
  3. Fix any errors
  4. Repeat until all tests pass
  5. Commit and push (hooks will block if tests fail)

Getting started:

Deployment

Site deploys automatically to GitHub Pages when pushed to the main branch. Custom domain www.j3zz.com is configured via CNAME file.

Deployment workflow:

  1. Run tests locally (./test-before-push.sh or automatic via Lefthook)
  2. All tests pass → push to main branch
  3. GitHub Actions builds the site with Jekyll
  4. Deploys to GitHub Pages immediately

⚠️ Important: GitHub Actions does NOT run tests - it only builds and deploys. Your local Lefthook hooks are the ONLY quality gate.

Note: This site uses the github-pages gem for compatibility with GitHub Pages infrastructure.

Code Quality & Best Practices

This codebase follows modern web development best practices and maintains high code quality standards.

JavaScript Quality

Modern Standards:

Performance Utilities:

Files:

Accessibility

ARIA Support:

Implementation:

Security

HTTP Security Headers:

Error Handling:

File: _includes/seo.html contains security meta tags

Performance

Script Loading:

CSS:

Maintainability

CSS Custom Properties:

Variables Available:

Modular Architecture:

Code Quality Score

Based on modern web development best practices:

Category Score Status
JavaScript Quality 9.5/10 ✅ Excellent
Accessibility 9/10 ✅ Strong
Security 8.5/10 ✅ Good
Performance 8/10 ✅ Good
Maintainability 9/10 ✅ Excellent
SEO 9/10 ✅ Comprehensive
Error Handling 9/10 ✅ Robust

Overall: 8.9/10 - Top 10-15% of websites in code quality.

Future Enhancements (Optional)

Consider these advanced improvements if needed:

Need Help?