CLAUDE.md

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

Project Overview

Personal portfolio and blog site for Zoë Farmer (ML/AI Engineer) at dataleek.io. Built with Jekyll using a fully custom dark theme (JupyterLab-inspired, no remote theme dependency).

Development Commands

Use just (see justfile in repo root) for all common tasks:

just serve       # Install deps and serve with live reload
just build       # Install deps and build static site
just install     # Install Ruby gem dependencies only
just notebooks   # Convert Jupyter notebooks (.ipynb) to markdown posts
just assets      # Convert all PDFs to page-image grids (Ghostscript)
just assets resume  # Convert PDF resume to PNG page images only

Python dependencies are managed with uv. The root pyproject.toml declares a workspace with presentations/ as a member. Use uv run / uv add — never pip.

Architecture

• _config.yml — Jekyll config: KaTeX math engine, social links, site metadata (title/subtitle drive the header)
• index.md / 1_resume.md — Main content pages (home and resume)
• _layouts/ — Layout hierarchy: default.html wraps everything; home.html, page.html, post.html, college.html, resume.html extend it
• _includes/ — header.html (sticky nav with pipe separator), footer.html (mobile nav toggle JS inline), head.html (OG/SEO meta), pdf-gallery.html (lightbox thumbnail grid — see below)
• _sass/ — Custom SCSS design system (see below)
• assets/css/main.scss — SCSS entry point that imports all partials
• college/ — Academic notes and projects; college/code.md, college/data.md, college/math.md are section index pages
• presentations/ — Reveal.js presentations; each is a PDF (exported from JupyterLab RISE) with a Jekyll index.md that uses the pdf-gallery include
• projects/ — Project showcase pages
• college/notes/ — LaTeX course notes; each subject dir has a Makefile that builds PDFs with xelatex --shell-escape

SCSS Design System

All design tokens live in _sass/_variables.scss:

• Color palette: Feminine accent palette ($fem-rose, $fem-lavender, $fem-teal, $fem-purple, $fem-sky) mapped to semantic roles ($accent-primary, $accent-code, $accent-math, etc.)
• Surfaces: Dark warm-purple palette ($surface-page: #252030, $surface-cell: #2c2840, $surface-code: #32304a)
• Spacing: $space-1 through $space-16 (rem-based scale, note: $space-5 does not exist — use $space-4 or $space-6)
• Typography: Inter (sans) + Comfortaa (display/headings) + JetBrains Mono (mono); $text-xs through $text-4xl
• All SCSS variables are also exported as CSS custom properties on :root (e.g. --accent-primary, --surface-page)

Key SCSS partials:

• _notebook.scss — .nb-notebook wrapper gives content the notebook-cell aesthetic; applied automatically in layouts
• _nav.scss — Sticky header with pipe separator (.site-nav__sep) hidden in mobile drawer
• _home.scss — Hero section and image tile grid for the homepage
• _images.scss — PDF gallery thumbnails, hover effects, aspect-ratio handling for the pdf-gallery include
• _resume.scss — Resume page layout
• _college.scss — College section styles
• _silly.scss — Silly mode styles

PDF Gallery Include

_includes/pdf-gallery.html renders a PDF as a responsive thumbnail grid with a lightbox viewer (keyboard navigation: arrow keys, Escape). Parameters:

Parameter	Description
pdf	Path to the PDF download link
dir	Directory containing pre-converted page-N.png images
pages	Total page count
id	Unique slug (used for DOM IDs)
landscape	Optional; set for widescreen aspect ratio

Page images are generated by uv run assets/build_assets.py pdfs, which outputs {pdf_parent}/{pdf_stem}/page-N.png at 200 DPI using Ghostscript.

Content Conventions

• Pages use Jekyll front matter with layout, title, description, and nav-menu fields
• Math rendering via KaTeX (configured in _config.yml under kramdown)
• Conventional commits: feat:, fix:, docs:, refactor:
• The site owner’s name is Zoë (with diaeresis) — use the correct spelling