CLAUDE.md

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

Overview

This is a Jekyll-based academic portfolio site (carljstone.com) built on the Academic Pages template, which extends Minimal Mistakes. It’s a personal website for a microbial evolution researcher.

Development Commands

Local development:

bundle install
bundle exec jekyll serve -l -H localhost

Docker (alternative):

docker compose up
# Site available at localhost:4000

JavaScript build:

npm run build:js    # minify JS assets
npm run watch:js    # watch and rebuild on changes

CV utilities:

python scripts/cv_markdown_to_json.py   # convert _pages/cv.md to _data/cv.json
bash scripts/update_cv_json.sh          # wrapper for the above

Content generation (bulk markdown from data):

Edit TSV files in markdown_generator/, then run the corresponding .ipynb or .py scripts
publications.tsv → _publications/ via publications.ipynb
talks.tsv → _talks/ via talks.ipynb

Architecture

Content Collections

Content lives in Jekyll collections. Each item is a markdown file with YAML frontmatter:

Directory	Layout	Purpose
`_pages/`	various	Primary site pages (about, CV, research, publications, talks)
`_publications/`	`single`	Academic papers — frontmatter includes `venue`, `paperurl`, `citation`, `category`
`_talks/`	`talk`	Conference presentations — drives the talkmap feature
`_posts/`	`single`	Blog posts
`_teaching/`	`single`	Teaching materials
`_portfolio/`	`single`	Portfolio projects

Key Configuration Files

_config.yml — main Jekyll config (site metadata, collection definitions, default layouts, plugins)
_data/navigation.yml — main navigation menu items
_data/authors.yml — author profile info (social links, bio)
_data/cv.json — structured CV data (auto-generated from _pages/cv.md)

Theme System

The site uses a fork of Minimal Mistakes with custom layouts:

_layouts/ — page templates (single.html, talk.html, cv-layout.html, archive.html)
_includes/ — reusable HTML partials (author profile, masthead, SEO, analytics)
_sass/ — SCSS source (compiled to assets/css/main.css)

Do not edit assets/css/main.css directly — it is compiled from _sass/.

Talkmap Feature

_pages/talkmap.html renders an interactive map of conference locations. The underlying location data is auto-generated by talkmap.ipynb (run via GitHub Actions when talks content changes). The workflow is in .github/workflows/scrape_talks.yml.

Collections vs. Pages

_pages/ items appear in navigation and are standalone pages
Collection items (_publications/, _talks/, etc.) are aggregated on archive pages (_pages/publications.html, _pages/talks.html) using Jekyll’s site.publications, site.talks etc.
Publication category frontmatter (manuscripts, conferences, books) controls grouping on the publications page

Updating the CV

_pages/cv.md is the single source of truth for the web CV. To update: edit cv.md directly, then push to GitHub. Jekyll rebuilds automatically.

Optionally regenerate the JSON version (used by the cv-json layout if ever re-enabled):

python scripts/cv_markdown_to_json.py

Key Site URLs

commaKit GitHub: https://github.com/carl-stone/comma
commaKit docs (pkgdown): https://carl-stone.github.io/comma/
Joint Congress 2024 talk (YouTube): https://www.youtube.com/watch?v=QsKwKt1AudM&t=3420s

Reference File

carl_stone_reference.md is a professional context document for Claude’s use. It is listed in .gitignore and is never pushed to GitHub.

Carl Stone