CLAUDE.md

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

Project Overview

Jekyll-based academic website for Dr. Will Barker (wevbarker.co.uk), a theoretical physicist. Hosted on GitHub Pages via GitHub Actions (not the default Pages build). Uses the Minima theme with extensive custom overrides. Deploys from the master branch.

Development Commands

Server (REQUIRED for all work)

./serve.sh                    # Start dev server (kills existing, runs on port 4000, no-watch mode)
./serve.sh -k                 # Kill all Jekyll processes without restarting
bundle exec jekyll build      # Manual rebuild (required after edits since --no-watch)
bundle exec jekyll clean      # Clean generated files

TypeScript & Linting

npm run build:ts              # Compile TypeScript (assets/js/src/ -> assets/js/dist/)
npm run watch:ts              # Watch mode for TypeScript
npm run lint:fix              # ESLint auto-fix
npm run build                 # Full build: TS compile + lint + format
npm run test                  # Lint + typecheck + asset budgets
npm run typecheck             # TypeScript type checking only

Asset Pipeline (Gulp-based)

npm run assets:build          # Full asset build (images, JS, CSS)
npm run assets:dev            # Development asset build with watch
npm run assets:budgets        # Check performance budgets

Debugging

./debug-devtools.sh           # Launch Chromium with remote debugging + console capture
# Logs: logs/devtools-debug.log, logs/console-capture.log

Monitor Server Logs

After making changes, always check for build errors:

tail -50 logs/serve.log | grep -E "(ERROR|not found|LoadError)" | tail -20

Architecture

Jekyll Structure

  • Layouts: _layouts/default.html (base), home.html, page.html
  • Includes: _includes/ - head.html (main head with analytics, MathJax, meta), header.html, footer.html, plus component includes (photo-reel.html, lazy-pdf.html, responsive-image.html, repository-card.html, inline-code-fix.html, json-ld.html, meta-tags.html)
  • Styles: _sass/ organized as abstracts/, base/, components/, layout/ plus minima/ theme overrides
  • Config: _config.yml - site settings, navigation (header_pages), plugin config, SEO settings

Pages (root *.md files)

Navigation order defined by header_pages in _config.yml: index.md, PageCV.md, PagePublications.md, PageSoftware.md, PageTheses.md, PageUndergraduate.md, PageGraduate.md, PageDoctoral.md, PageInternships.md, PageSeries.md, PageOutreach.md, PageBlog.md

Frontend TypeScript (assets/js/src/)

Entry point: main.ts. Compiled to assets/js/dist/.

  • modules/academic/ - PublicationsList, PublicationCard, BibTeXGenerator, PDFPreview, CitationTooltip, InspireHEP
  • modules/ui/ - Modal, Navigation, LazyLoading
  • utils/ - Helpers, Analytics, DynamicTitleSizing, CodeBlockManager

Data (_data/)

  • repos/*.json - Repository metadata for software project cards (psalter, higgs, xplain, hamilcar, etc.)
  • photo_reels.yml - Photo carousel configurations
  • theme-colors.yml - Theme color definitions

Key Features

  • MathJax for mathematical notation (configured in head.html)
  • Rouge syntax highlighting with CodeBlockManager for copy-to-clipboard and theme support
  • Inline code fix (_includes/inline-code-fix.html) - JS that converts backtick patterns in HTML elements to <code> tags post-render
  • Repository cards - Include templates per software project, fed by _data/repos/*.json
  • Photo reels - Configurable image carousels via _data/photo_reels.yml
  • PDF embedding via pdfobject.js with lazy loading support

Deployment

  • Push to master triggers .github/workflows/pages.yml
  • GitHub Actions builds with Ruby 3.2, installs ImageMagick, runs jekyll build
  • Custom plugins supported (jekyll-compress-images, jekyll-minifier)
  • sync-readmes.yml syncs README files from external repos

Setup (Arch Linux)

sudo pacman -S ruby ruby-bundler
sudo bundle install
# If Ruby 3.4+ LoadErrors: erb, csv, base64, logger are already in Gemfile

Content Conventions

  • Blog posts: _posts/YYYY-MM-DD-title.md
  • Custom SCSS: _sass/minima/custom-styles.scss, _sass/components/
  • Assets organized by page: assets/PageUndergraduate/, assets/PageGraduate/, etc.
  • Background images: assets/backgrounds/ (cmb/, armillary/ subdirs)

Known Issues

  • _includes/head.html has hardcoded SRI hashes that may be incorrect for MathJax CDN resources
  • _config.yml has placeholder ORCID and Google Scholar IDs at lines 59-60 (social_links) while correct values exist at lines 141-142
  • serve.sh runs with --no-watch, so bundle exec jekyll build is needed after edits