CLAUDE.md

CLAUDE.md

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

Project Overview

An-Sheng Lee’s academic personal website (https://dispink.github.io), built on the Academic Pages Jekyll template (itself derived from Minimal Mistakes). Content is mostly author-authored Markdown; layout/styling comes from the upstream template.

Common Commands

Local preview (requires Ruby + bundler):

bundle install                       # one-time; delete Gemfile.lock first if errors
bundle exec jekyll serve -l -H localhost   # live-reload at http://localhost:4000

Production build (matches CI):

JEKYLL_ENV=production bundle exec jekyll build

JS asset pipeline (only when editing assets/js/):

npm run build:js     # uglifies vendor + plugins + _main.js into assets/js/main.min.js
npm run watch:js     # rebuild on change

Regenerating talk/publication Markdown from TSVs (optional authoring flow):

cd markdown_generator && python talks.py          # reads talks.tsv → writes ../_talks/*.md
cd markdown_generator && python publications.py   # reads publications.tsv → writes ../_publications/*.md

Regenerating the talk map (scrapes location: from each _talks/*.md, geocodes via Nominatim):

cd _talks && python talkmap.py   # outputs ../talkmap/{map.html, org-locations.js}

Deployment

.github/workflows/jekyll.yml deploys on push to master. It runs jekyll build with the Pages base_path and publishes _site/ via actions/deploy-pages. There is no staging environment — pushing master is publishing. _config.yml is not auto-reloaded by jekyll serve; restart the server after editing it.

Architecture

Standard Jekyll layout. The pieces that matter for editing:

  • Collections (configured in _config.yml under collections:): _publications, _talks, _portfolio, _teaching. Each file needs YAML front matter with at minimum title, collection, permalink, date. Filenames are conventionally YYYY-MM-DD-slug.md and drive sort order on archive pages.
  • _pages/: top-level pages (about.md is the homepage via permalink: /). publications.html, talks.html, teaching.html, portfolio.html, projects.md are the archive landing pages that iterate over their respective collections.
  • _data/navigation.yml: controls the top-nav menu. Editing a page’s permalink without updating this file leaves the nav stale.
  • _data/authors.yml + _config.yml author: block: drive the sidebar profile. Social links only render when their key is non-empty.
  • _layouts/ + _includes/ + _sass/: upstream template internals. Avoid editing unless deliberately customizing the theme — changes here conflict with any future template sync.
  • files/: static assets served at /files/... (e.g. CV PDF linked from nav as /files/CV_ASL.pdf).
  • markdown_generator/: optional TSV→Markdown pipeline for bulk publication/talk entry. The .ipynb and .py variants do the same thing.
  • talkmap/: generated output of _talks/talkmap.py; regenerate after adding a talk with a new location: value.

Content Conventions

  • Upstream template ships with placeholder files (e.g. _publications/2009-10-01-paper-title-number-1.md) that are clearly demo content — don’t treat them as real when summarizing the author’s work.
  • Permalinks in collection front matter should match the permalink: pattern defined in _config.yml (/:collection/:path/).
  • future: true in _config.yml means posts/talks dated in the future are published immediately — intentional for upcoming talks.

Devcontainer

.devcontainer/install-dev-tools.sh runs on container create: deletes Gemfile.lock, installs Ruby + bundler, runs bundle install, installs Python deps from requirements.txt (pandas + jupyter stack for the markdown generators), and installs the Claude Code CLI globally. postStartCommand runs jekyll --version as a smoke test.