CLAUDE.md

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

Claude OAuth Token Management

The repository uses automated OAuth token management for Claude integration:

  • Initial Setup: Run the Claude OAuth workflow manually to authenticate
  • Automatic Refresh: Tokens are automatically refreshed every 6 hours to prevent expiry gaps
  • Monitoring: Daily health checks with automated issue creation for token problems
  • Token Storage: Tokens are securely stored as GitHub secrets:
    • CLAUDE_ACCESS_TOKEN: OAuth access token
    • CLAUDE_REFRESH_TOKEN: OAuth refresh token
    • CLAUDE_EXPIRES_AT: Token expiration timestamp

Workflows:

  1. claude-oauth.yml: Initial OAuth setup (manual)
  2. claude-oauth-refresh.yml: Automatic token refresh (scheduled every 6 hours)
  3. claude-oauth-monitor.yml: Health monitoring and alerting (daily + on refresh completion)
  4. claude.yml: Main Claude PR assistant for regular code reviews
  5. claude-renovate.yml: Specialized Claude assistant for Renovate dependency updates

Project Overview

This is a Jekyll-based static website hosted on GitHub Pages. Jekyll is a static site generator that transforms Markdown content and templates into a complete website.

Core Features

  • Static site generation with Jekyll
  • GitHub Pages hosting
  • Markdown-based content management
  • Liquid templating engine
  • Responsive design

Architecture Overview

  • Platform: Jekyll static site generator
  • Language: Ruby (Jekyll), HTML, CSS, JavaScript
  • Templates: Liquid templating engine
  • Content: Markdown files
  • Hosting: GitHub Pages
  • Build: Automated via GitHub Actions

CI/CD Overview

The project uses GitHub Actions for automated deployment:

Automated Deployment:

  • jekyll-gh-pages.yml: Jekyll build and GitHub Pages deployment

Code Review:

  • claude.yml: Automated code review for regular PRs
  • claude-renovate.yml: Specialized review for dependency updates

Note: The site automatically builds and deploys when changes are pushed to the main branch.

Jekyll Development

Local Development

# Install dependencies
bundle install

# Serve locally with live reload
bundle exec jekyll serve --livereload

# Build the site
bundle exec jekyll build

Directory Structure

  • _config.yml - Jekyll configuration
  • _layouts/ - Page templates
  • _includes/ - Reusable components
  • _posts/ - Blog posts (if applicable)
  • _data/ - Data files (YAML, JSON, CSV)
  • assets/ - CSS, JS, images
  • index.md or index.html - Homepage

Content Guidelines

Markdown

  • Use standard Markdown syntax
  • Front matter for metadata
  • Consistent heading hierarchy
  • Proper image alt text

SEO

  • Descriptive page titles
  • Meta descriptions
  • Semantic HTML
  • Proper heading structure

Accessibility

  • Alt text for images
  • Proper contrast ratios
  • Keyboard navigation
  • ARIA labels where needed

PR Review Context

When reviewing PRs for this Jekyll site, focus on:

  1. Content Quality
    • Grammar and spelling
    • Clarity and accuracy
    • Proper formatting
  2. Technical Aspects
    • Valid HTML/CSS
    • JavaScript best practices
    • Performance optimization
    • SEO considerations
  3. Design Consistency
    • Visual consistency
    • Responsive design
    • Cross-browser compatibility

Available tools: You have access to Perplexity MCP to research any technical aspects relevant to Jekyll, web standards, or best practices.

Code Review Accuracy Requirements

CRITICAL: Always verify your findings before reporting issues:

Verification Process

  1. Read Before Claiming: Always use the READ tool to examine files before stating issues exist
  2. Verify Line Numbers: Check actual file content to confirm line numbers and code snippets
  3. Test Locally: Consider how changes affect the built site
  4. Cross-Reference: Compare with Jekyll documentation
  5. Fresh Context: Do not rely on cached information

What NOT to Do

  • ❌ Make claims about code without reading the current file state
  • ❌ Reference line numbers without verifying them
  • ❌ Assume previous review findings are still valid
  • ❌ Report issues based on outdated information
  • ❌ Make broad statements without specific evidence

Jekyll-Specific Guidelines

Performance

  • Minimize includes and nested loops
  • Optimize images before adding
  • Use lazy loading for images
  • Minimize JavaScript usage

Security

  • Sanitize user inputs if any
  • Avoid inline scripts
  • Use HTTPS for external resources
  • Keep dependencies updated

Best Practices

  • Use semantic HTML5 elements
  • Implement structured data
  • Ensure valid HTML/CSS
  • Follow Jekyll conventions

Development Workflow

  1. Before starting: Review Jekyll documentation if needed
  2. During development: Test locally with jekyll serve
  3. Before committing:
    • Validate HTML/CSS
    • Check for broken links
    • Test responsive design
    • Verify build success
  4. After merge: Verify GitHub Pages deployment

Configuration Management

_config.yml

  • Site settings and metadata
  • Build options
  • Plugin configuration
  • Navigation structure

Environment-Specific Settings

  • Development vs. production URLs
  • Analytics codes
  • API keys (use secrets)

Content Management

Adding New Pages

  1. Create Markdown or HTML file
  2. Add front matter
  3. Link from navigation
  4. Test locally

Updating Existing Content

  1. Edit Markdown files
  2. Preview changes locally
  3. Check formatting
  4. Verify links

Deployment

The site automatically deploys to GitHub Pages when changes are pushed to the main branch. The jekyll-gh-pages.yml workflow handles:

  • Building the Jekyll site
  • Deploying to GitHub Pages
  • Caching for faster builds

Troubleshooting

Common issues and solutions:

  • Build failures: Check Jekyll version compatibility
  • Missing styles: Verify asset paths
  • Broken links: Use relative URLs
  • Deploy issues: Check GitHub Pages settings