CLAUDE.md

Guidance for working on this repository.

What this is

Arthur Ouaknine’s personal academic website, served at https://arthurouaknine.github.io. It is a Jekyll site, originally forked from the Academic Pages template (itself a fork of the Minimal Mistakes theme). It is deployed via GitHub Pages from the master branch — pushing to master publishes the live site, so be deliberate about what gets committed.

The visual design has been customized away from the stock theme (nature-inspired green/blue palette, custom cards, custom publication-link buttons). See MODERNIZATION_SUMMARY.md for the history of that redesign.

Common workflow

Most work is adding content to existing structure (a new publication, project, talk, news item). Occasionally we add new sections or change the structure. Match the existing patterns — this site relies heavily on hand-written HTML/Markdown blocks with specific CSS classes rather than auto-generated layouts, so consistency matters.

Running locally

bundle install        # first time, or after Gemfile changes (delete Gemfile.lock if it errors)
bundle exec jekyll serve   # serves at http://localhost:4000, auto-rebuilds on change

The site uses the github-pages gem to mirror the GitHub Pages build environment. _site/ is the generated output (gitignored) — never edit it by hand.

Local build gotcha: the local SCSS toolchain reads files as US-ASCII and chokes on the accented characters in some .scss files (Invalid US-ASCII character error). GitHub Pages builds fine; locally, force a UTF-8 locale: LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 bundle exec jekyll serve. Editor backup files (*~) are also gitignored; ignore the stray *~ and .html~ files already in the tree.

Repository layout

Path	Purpose
`_config.yml`	Site-wide config: title, author/social links, collections, plugins, defaults. Restart `jekyll serve` after editing — it is not hot-reloaded.
`_pages/`	Top-level pages (about, publications, talks, teaching, cv, codeanddata, etc.). The homepage is `about.md` (`permalink: /`).
`_data/navigation.yml`	The top navigation menu. Edit this to add/remove/reorder nav links.
`_data/`	Other site data: `authors.yml`, `ui-text.yml` (theme strings), `comments/`.
`_codeanddata/`	“Code and Data” collection — one Markdown file per project/dataset.
`_talks/`, `_teaching/`, `_portfolio/`, `_posts/`, `_drafts/`	Other collections / blog posts.
`_layouts/`	Page layouts (`single`, `archive`, `talk`, `splash`, `default`).
`_includes/`	Reusable Liquid partials, e.g. `project-card.html`, `publication-card.html`, sidebar, masthead.
`_sass/`	SCSS partials. Custom styling lives mainly in `_cards.scss` and `_variables.scss`.
`assets/`	Compiled CSS entrypoint (`css/main.scss`), JS, fonts.
`images/`	All site images (teasers, photos, favicons). Referenced as `/images/<file>`.
`files/`	Downloadable assets (CV PDF, posters). Served at `/files/<file>`.
`markdown_generator/`	Optional Python/Jupyter scripts to generate publication/talk Markdown from TSV. Not part of the normal manual workflow.

How to add content

A publication

Publications are not auto-generated from a collection — they are hand-written HTML blocks in _pages/publications.md, grouped under <div class="section-header"> sections (“Conferences and Journals”, “PhD Thesis”, “Blog Posts”). Add new entries at the top of the relevant section (newest first). Follow this exact pattern:

**Paper Title Here**  
author-one, <strong>Arthur Ouaknine</strong>, author-three.  
*Venue Year*  
<a href="https://arxiv.org/abs/..." class="pub-link pub-link--paper">Paper</a>
<a href="https://github.com/..." class="pub-link pub-link--code">Code</a>
<a href="https://huggingface.co/datasets/..." class="pub-link pub-link--dataset">Dataset</a>  

The author line is rendered from the co-author database (see below) — list the keys in order, comma-separated, inside ....
Trailing two spaces on a line force a line break (Markdown). Keep them.
Link button classes (defined in _sass/_cards.scss): pub-link--paper (green), pub-link--code (blue), pub-link--dataset (purple), pub-link--poster (orange), pub-link--page (gray), pub-link--video (red). Always include the base pub-link class too.

Co-author database (auto-linking author names)

Co-authors live in _data/coauthors.yml, keyed by an ascii kebab-case slug:

some-coauthor:
  name: "Some Coauthor"   # display name, accents allowed
  url: "https://their-site.example"   # optional; omit/blank = plain text, no link

Render names anywhere with _includes/authors.html: some-coauthor, <strong>Arthur Ouaknine</strong>, other-person. Per key it emits: the owner (me: true, i.e. arthur-ouaknine) bold and unlinked; anyone with a url as a subtle .author-link (inherits text color, faint highlight on hover only — no link color); everyone else as plain text. An unknown key prints verbatim so the gap is visible.

When adding a publication: reuse existing keys, and add new co-authors to coauthors.yml (with url if known, blank otherwise). Filling in a url later auto-links that person across every publication that references the key — no need to touch the publication entries again.

A code/data project

Create a new file in _codeanddata/ named NN_slug.md (the NN_ numeric prefix controls order; the page lists them reversed, so higher numbers appear first). Frontmatter:

---
title: "Project Title"
excerpt: "<br/><img src='/images/PROJECT_teaser.png' width=600px height=auto><br>"
collection: codeanddata
permalink: /codeanddata/slug
venue: "Venue Year"
---

The excerpt’s <img src=...> is parsed by _includes/project-card.html to extract the card thumbnail — keep an image in the excerpt. Body typically contains: author list, venue, an Abstract section, the teaser image (<img ... class="center">), links to code/data, and a BibTeX citation block. See _codeanddata/05_selvabox.md as the model. Put the teaser image in images/.

A talk

Talks shown on the site are hand-written HTML blocks in _pages/talks.md, grouped under section headers (“Conferences and Workshops”, “Others”), newest first:

**Talk / Venue Title**  
Location — Month Year  
<a href="https://..." class="pub-link pub-link--video">Recording</a>

(The _talks/ collection still exists with old template stubs but the live Talks page is driven by the hand-written list in talks.md.)

A news item

Edit the “Latest News” block in _pages/about.md. Add to the top of <div class="news-section">:

<div class="news-item">
  <span class="news-item__date">MM/YYYY</span>
  <div class="news-item__content">Your news, with <a href="..." target="_blank">links</a>.</div>
</div>

Add a - title: / url: pair under main: in _data/navigation.yml.

Styling conventions

Edit colors and design tokens in _sass/_variables.scss; custom components (cards, buttons, news items, section headers, pub-links) live in _sass/_cards.scss.
New SCSS partials must be @import-ed from assets/css/main.scss.
Reusable visual building blocks already available: .section-header, .news-item, .card, .projects-grid / .publications-grid, .btn-modern (--primary/--secondary/--outline), and the .pub-link--* variants. Prefer reusing these classes over inline styles when adding new sections, so the look stays consistent.

Conventions & cautions

Author name is always written Arthur Ouaknine (bold when in an author list).
Internal asset links are root-relative: /images/..., /files/....
Pushing to master deploys live. Only commit/push when asked.
Don’t hand-edit _site/, Gemfile.lock (regenerated), or the *~/*.html~ backup files.
When adding structurally new pages/collections, register them in _config.yml (collections: / defaults:) and restart the local server.

Arthur Ouaknine