Gaurav Vipat

Gaurav Vipat

MLSys PhD student at UTNS

CLAUDE.md

CLAUDE.md

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

What this is

Gaurav Vipat’s personal academic portfolio site, built on the Academic Pages Jekyll template (a fork of Minimal Mistakes). It’s a static site deployed via GitHub Pages at gvipat.github.io. There is no application code to compile — content lives in Markdown/YAML collections, and Jekyll renders it into HTML via Liquid templates in _layouts/ and _includes/.

Common commands

Local development (native):

bundle install                        # install Ruby deps (delete Gemfile.lock and retry on errors)
bundle exec jekyll serve -l -H localhost   # serve at localhost:4000, live-reloads on .md/.html changes

Changes to _config.yml require stopping and restarting the server — it is not hot-reloaded.

Local development (Docker / VS Code Dev Container):

chmod -R 777 .
docker compose up                     # site available at localhost:4000

Or reopen the repo in the VS Code Dev Container (.devcontainer/devcontainer.json); it builds from Dockerfile and runs jekyll serve with _config.yml,_config_docker.yml.

Production build (what CI runs, see .github/workflows/jekyll-build.yml):

bundle exec jekyll build --strict_front_matter

There is no linter or test suite in this repo — treat a successful strict-front-matter build as the correctness check.

JS asset build (only needed when editing assets/js/):

npm run build:js     # uglifies jquery + assets/js/plugins/jquery.greedy-navigation.js + assets/js/_main.js + theme.js -> assets/js/main.min.js
npm run watch:js      # rebuild on change

Content architecture

Content is organized as Jekyll collections, each a directory of Markdown files with YAML front matter, rendered through a matching layout:

  • _posts/ — blog posts (archive-single.html via default.html)
  • _publications/ — papers, one file per publication (front matter drives the publications archive page)
  • _talks/ — talks/tutorials, rendered with _layouts/talk.html and _includes/archive-single-talk.html; also feeds talkmap.html
  • _teaching/, _portfolio/ — same collection pattern
  • _pages/ — standalone pages (About, CV, Publications index, Talks index, 404, etc.), addressed by permalink in front matter, not by file path
  • _drafts/ — posts excluded from build until dated/published

The template’s sample entries have been removed from _posts/, _publications/, _talks/, _teaching/, and _portfolio/ — those collections are currently empty. When adding real content, follow the front-matter conventions documented on _pages/markdown.md (the site’s own /markdown/ guide page) rather than reintroducing the old placeholder files.

Site-wide behavior and content are controlled by _config.yml (author/social profile fields, theme, plugins, collections config) — most personalization (name, bio, social links, avatar) happens there, not in code.

_data/ holds structured YAML/JSON consumed by templates:

  • navigation.yml — top nav links
  • ui-text.yml — locale strings
  • authors.yml — author bios (for multi-author sites)
  • cv.json — structured CV data consumed by _includes/cv-template.html (rendered on the /cv-json/ page); generated from _pages/cv.md, not hand-edited (see below)
  • comments/ — flat-file comments (staticman-style), organized by post slug

Generating content from external sources

Several one-off scripts turn external/structured data into the Markdown files above. They are meant to be run manually, not as part of the build:

  • markdown_generator/ — converts a TSV/BibTeX/ORCID export into _publications/*.md and _talks/*.md. .py files (publications.py, pubsFromBib.py) are the low-dependency CLI versions (e.g. python3 publications.py publications.csv); the .ipynb counterparts are the documented/interactive versions.
  • scripts/update_cv_json.sh + scripts/cv_markdown_to_json.py — regenerates _data/cv.json from _pages/cv.md (source of truth is the Markdown CV, JSON is derived — do not hand-edit cv.json).
  • talkmap.ipynb / talkmap.py / talkmap/ — geocodes talk locations from _talks/ into talkmap/org-locations.js, used by _pages/talkmap.html. Re-run automatically by .github/workflows/scrape_talks.yml whenever _talks/** or talkmap.ipynb changes (executes the notebook and pushes the regenerated output).

CI workflows (.github/workflows/)

  • jekyll-build.yml — runs after bad-pr.yml completes on main; builds the site with --strict_front_matter (front-matter typos fail the build).
  • bad-pr.yml — auto-closes/locks PRs that look like someone pushed personal-site changes to the upstream template repo (checks PR body for the template’s boilerplate warning text).
  • close-tests.yml — auto-closes issues that look like connectivity/spam test issues.
  • scrape_talks.yml — regenerates the talk map data (see above) and commits it back.

Note: bad-pr.yml and close-tests.yml are template-repo-maintenance workflows inherited from upstream academicpages/academicpages.github.io; they’re generally irrelevant once this is a personal fork but are left intact.