CLAUDE.md

CLAUDE.md

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

What this is

Parker Howell’s personal academic website (https://parker-howell.github.io), built on the academicpages Jekyll theme (a fork of Minimal Mistakes) and served via GitHub Pages. Most edits are content edits to Markdown/data files, not code.

Build & serve

The site is Ruby/Jekyll. Two supported workflows:

# Local Ruby toolchain
bundle install
bundle exec jekyll serve -l -H localhost   # live-reload at http://localhost:4000

# Docker (no local Ruby needed) — serves with live reload on :4000
docker-compose up

Notes:

  • _config.yml is not reloaded on jekyll serve; restart the server after editing it.
  • The Docker workflow layers _config_docker.yml over _config.yml (sets JEKYLL_ENV=docker, url: "").
  • _site/ is the generated output — never edit it by hand; it is overwritten on every build.

JavaScript assets

JS is hand-concatenated/minified into assets/js/main.min.js via npm + uglify-js (not part of the Jekyll build):

npm install
npm run build:js   # rebuild assets/js/main.min.js from sources
npm run watch:js   # rebuild on change

Content model

Content lives in Markdown with YAML front matter, not in templates. Key locations:

  • _pages/ — top-level pages. The site is a single page: about.md (homepage via permalink: /) holds every section, each wrapped in <section id="..."> (e.g. #about, #research) with markdown="1" so Markdown renders inside. The sidebar menu (_data/navigation.yml) links to those anchors. Other pages: 404.md, sitemap.md, terms.md.
  • _data/ — site data: navigation.yml (nav bar), authors.yml, ui-text.yml, cv.json.
  • _config.yml — site + author config. The author: block (avatar, email, employer, social links) drives the sidebar profile rendered by _includes/author-profile.html. Blank social fields are hidden automatically.
  • files/ — downloadable assets (e.g. parker-howell-cv.pdf, paper PDFs linked from research.md).
  • images/ — site images including the sidebar headshot referenced by author.avatar.

The theme also defines collections in _config.yml (_publications, _talks, _teaching, _portfolio) that output to /:collection/:path/. These directories are not currently present — this site lists research inline in the #research section of about.md instead. Adding one of those directories re-enables that collection.

Rendering pipeline: front matter layout: → _layouts/*.html → composed from partials in _includes/ → styled by _sass/ (compiled to assets/css/). To change page structure edit layouts/includes; to restyle edit _sass/.

CV → JSON generation

_data/cv.json is generated, not edited directly. It is produced from a Markdown CV by:

./scripts/update_cv_json.sh

This runs scripts/cv_markdown_to_json.py, which expects _pages/cv.md (currently absent) plus the theme collection directories, parses them into JSON Resume format, and writes _data/cv.json. If you change the CV, regenerate the JSON rather than editing it by hand.

Talk map automation

.github/workflows/scrape_talks.yml runs talkmap.ipynb (geocoding talk locations) whenever talks/**, _talks/**, or talkmap.ipynb change on push, then auto-commits talkmap_out.ipynb. Expect bot commits (“Automated update of talk locations”) on this branch.

Deployment

Pushing to master deploys via GitHub Pages — there is no manual deploy step. The github-pages gem pins the plugin/version set GitHub Pages supports, so stay within those plugins (see Gemfile).