Younesse Kaddar

Younesse Kaddar

Hi! My name is Younesse Kaddar. I'm a computer science PhD student at the University of Oxford, UK. Welcome to my website!

CLAUDE.md

CLAUDE.md

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

🚨 CRITICAL RULES (READ FIRST) 🚨

STOP AND VERIFY Before Creating ANY File

  1. 🚨 DO NOT CREATE NEW COLLECTION DIRECTORIES MANUALLY
    • ❌ BAD: mkdir _New-collection
    • ✅ GOOD: ./add_new_collection.sh "New-collection" "Display Name"
  2. 🚨 DO NOT CREATE ARCHIVE PAGES
    • Archive pages are auto-generated by add_new_collection.sh
    • They follow a strict template and naming convention
  3. 🚨 DO NOT MODIFY _config.yml FOR COLLECTIONS
    • The script handles all necessary configuration
    • Manual edits will break the automation comments
  4. 🚨 DO NOT CREATE DOCUMENTATION FILES UNLESS REQUESTED
    • No README.md files in collections
    • No documentation unless explicitly asked
  5. 🚨 ALWAYS CHECK IF FUNCTIONALITY EXISTS
    • Search for existing utilities before creating new ones
    • Use existing layouts and includes
    • Reuse existing JavaScript modules

File Creation Checklist

Before creating ANY file, ask yourself:

  • Does this file already exist somewhere?
  • Is there a script that should create this?
  • Am I following the existing naming patterns?
  • Is this file actually needed?
  • Did the user explicitly request this file?

DRY Principle Enforcement

  • Search First: Use Grep/Glob to find similar functionality
  • Reuse Components: Check _includes/ and _layouts/
  • Extend, Don’t Duplicate: Modify existing files when possible

Project Overview

Purpose and Goals

This is a Jekyll-based academic portfolio website for Younesse Kaddar, a PhD student at the University of Oxford. The site serves multiple purposes:

  • Academic course materials (40+ courses from L3 to M2 level)
  • Research documentation and publications
  • Blog posts on technical topics
  • Interactive tools (LLM API pricing comparison)
  • Professional portfolio and CV

Tech Stack

  • Static Site Generator: Jekyll 4.3.4
  • Theme: Minimal Mistakes (remote theme)
  • Hosting: GitHub Pages (custom domain: younesse.net)
  • JavaScript Build: npm with uglify-js
  • Mathematical Rendering: MathJax 3 with XyPic support
  • Ruby Version: Managed via rbenv
  • Key Dependencies: See Gemfile and package.json

Architecture Overview

├── _[Collection-name]/     # 40+ academic collections
├── _data/                  # Site data (navigation, authors, UI text)
├── _includes/              # Reusable components
├── _layouts/               # Page templates
├── _pages/                 # Static pages and archive pages
├── _posts/                 # Blog posts
├── _sass/                  # SCSS stylesheets
├── assets/                 # JS, CSS, images, PDFs
├── ipynb/                  # Jupyter notebook conversion
├── _config.yml            # Main Jekyll configuration
└── Utility scripts (.sh)   # Automation tools

Best Practices

Be Clear and Direct

  • Use existing CLI tools: bundle exec jekyll serve, npm run build:js
  • No wrapper scripts: Use Jekyll/npm commands directly
  • Configuration via CLI: Use command-line flags, not new config files

Handle Academic Content Properly

  • French collections: Use Cours, TD, DM, TP naming
  • English collections: Use Lecture, Exercises, ProblemSet
  • Consistent metadata: Always include title, date, author in front matter

JavaScript Development

  • Build after changes: Always run npm run build:js
  • Test locally: Use bundle exec jekyll serve
  • No direct edits to main.min.js: Edit source files only

Clean Development

  • Delete temporary files: Remove any debug or test files
  • No console.log in production: Remove debugging statements
  • Clean commits: No WIP or debug commits

Code Conventions

File Naming Patterns

# French Collections
Cours[N].md          # Main lectures
TD[N].md            # Tutorial sessions
DM[N].md            # Homework
TP[N].md            # Lab work

# English Collections  
Lecture[N].md       # Main lectures
Exercises[N].md     # Exercise sheets
ProblemSet[N].md    # Problem sets

Front Matter Structure

---
title: "Clear, Descriptive Title"
author: "Younesse Kaddar"
date: YYYY-MM-DD
toc: true
tags: [tag1, tag2, tag3]
---

Import Organization

  1. Theme includes first
  2. Custom includes second
  3. Alphabetical within groups

Error Handling

  • Let Jekyll handle build errors
  • Don’t suppress error messages
  • Fix root causes, not symptoms

Common Workflows

Adding New Course Content

# 1. Navigate to collection
cd _Collection-name/

# 2. Create file following naming convention
# French: Cours3.md, TD3.md
# English: Lecture3.md, Exercises3.md

# 3. Add proper front matter
# 4. Test locally
bundle exec jekyll serve

Creating a New Collection

# ALWAYS use the script - NEVER do manually
./add_new_collection.sh "Collection-name" "Display Title" "(Subtitle1)" "(Subtitle2)"

# This automatically:
# - Creates the collection directory
# - Updates _config.yml
# - Updates _data/navigation.yml
# - Creates archive page in _pages/

Debugging Build Issues

# 1. Verbose build to see errors
bundle exec jekyll build --verbose

# 2. Check for missing files (common issue)
# 3. Verify _config.yml syntax
# 4. Check front matter formatting

🚨 CRITICAL: Running Jekyll Server in Claude Code

# ❌ PROBLEM: This will timeout in Claude Code!
bundle exec jekyll serve    # Runs forever, causes timeout

# ✅ SOLUTION: Use background process manager
/Users/youdar/bin/jekyll-server start    # Starts in background
/Users/youdar/bin/jekyll-server status   # Check if running
/Users/youdar/bin/jekyll-server stop     # Stop when done
/Users/youdar/bin/jekyll-server logs     # View server logs

# Alternative for one-time builds (no server):
bundle exec jekyll build     # Just builds, then exits

Why this happens: jekyll serve is a web server that runs indefinitely. Claude Code waits for commands to complete, causing a timeout. Any long-running server (npm run dev, python -m http.server, etc.) needs to be run in the background.

Key Rule: For servers and watchers, always use background process management or the provided jekyll-server script.

Updating JavaScript

# 1. Edit source files in assets/js/
# 2. Build and minify
npm run build:js

# 3. Test changes
bundle exec jekyll serve

# 4. Commit both source and built files

Converting Notebooks

# From collection directory
../ipynb/convert.sh notebook.ipynb

# Handles:
# - Markdown conversion
# - Image extraction
# - Front matter addition

Areas to Avoid

DO NOT MODIFY

  • _site/ - Generated output directory
  • .git/ - Git repository data
  • node_modules/ - npm packages
  • Files in theme remote (override in local files instead)

DO NOT CREATE

  • New scripts for existing CLI functionality
  • Duplicate layouts or includes
  • Test files in production directories
  • Configuration files for one-time use

DEPRECATED PATTERNS

  • Manual collection configuration
  • Direct _config.yml collection edits
  • Creating archive pages manually
  • Custom build scripts

Claude Code Specific Guidance

Preferred Tools

  • Search: Use Grep for content, Glob for files
  • Multi-edit: Use Edit for single files
  • Testing: Always bundle exec jekyll serve
  • Scripts: Use existing .sh files

When to Use TODO Maker

  • Planning multi-step collection additions
  • Organizing complex theme modifications
  • Tracking JavaScript refactoring steps
  • Managing content migration tasks

Decision Trees

“Should I create a new file?”

Is it course content? 
  YES → Follow naming convention in existing collection
  NO ↓
  
Is it a new collection?
  YES → Use add_new_collection.sh
  NO ↓
  
Does similar functionality exist?
  YES → Extend existing file
  NO ↓
  
Did user explicitly request it?
  YES → Create with clear purpose
  NO → DON'T CREATE

“How do I add this feature?”

Is it a visual change?
  YES → Check _sass/ and _layouts/
  NO ↓
  
Is it JavaScript functionality?
  YES → Add to assets/js/, run npm build
  NO ↓
  
Is it content organization?
  YES → Use existing patterns
  NO → Ask for clarification

Good vs Bad Examples

Adding Course Content

# ❌ BAD - Creating files everywhere
touch _NewCourse/index.md
touch _NewCourse/README.md
mkdir _NewCourse/assets

# ✅ GOOD - Following conventions
./add_new_collection.sh "NewCourse" "New Course Name"
# Then add content files following patterns

Modifying Themes

// ❌ BAD - New file for small change
// _sass/my-custom-styles.scss

// ✅ GOOD - Extend existing files
// Add to existing _sass/theme-toggle.scss or appropriate file

JavaScript Changes

# ❌ BAD - Direct minified edit
vim assets/js/main.min.js

# ✅ GOOD - Source edit + build
vim assets/js/theme-toggle.js
npm run build:js

Quick Reference

Most Used Commands

bundle exec jekyll serve    # Local development
npm run build:js           # Build JavaScript
git status                 # Check changes
git add -p                 # Stage selectively

File Location Guide

  • Course content → _[Collection]/
  • Blog posts → _posts/YYYY-MM-DD-title.md
  • Static pages → _pages/
  • JavaScript → assets/js/
  • Styles → _sass/
  • Data files → _data/

Emergency Fixes

  • Build fails: Check _config.yml syntax
  • 404 errors: Verify permalink in front matter
  • JavaScript not updating: Run npm run build:js
  • Theme not loading: Check remote_theme in _config.yml

Remember: This is a large, well-organized academic site. Respect the existing structure and patterns. When in doubt, search for existing examples before creating anything new.