CLAUDE.md

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

Project Overview

Personal academic website for Mengchao Zhang, built on the Academicpages template (fork of Minimal Mistakes Jekyll Theme). Hosted on GitHub Pages at zmccmzty.github.io.

Build & Development Commands

# Install Ruby dependencies
bundle install

# Local development server (http://localhost:4000)
bundle exec jekyll serve

# Local dev with config overrides (disables analytics, uses localhost URL)
bundle exec jekyll serve --config _config.yml,_config.dev.yml

# Minify JavaScript (requires Node.js)
npm run build:js

# Watch JS for changes
npm run watch:js

Deployment: Push to main branch triggers automatic GitHub Pages build. No manual build step needed.

Architecture

Jekyll static site with these content collections (each in _collectionname/ directory):

Publications (_publications/) — academic papers with venue, citation, thumbnail
Talks (_talks/) — conference/invited talks with type, venue, location
Teaching (_teaching/) — courses and workshops
Portfolio (_portfolio/) — project showcases

Key configuration:

_config.yml — site metadata, author profile, collection definitions, plugin list, default frontmatter
_config.dev.yml — local dev overrides (localhost URL, no analytics, expanded SASS)
_data/navigation.yml — main menu structure
_data/ui-text.yml — localized UI strings

Layout hierarchy: default.html → compress.html wrapper → specific layouts (single.html, archive.html, talk.html, splash.html). Components live in _includes/ (author-profile, masthead, sidebar, footer, SEO, analytics, comments).

Styling: SASS in _sass/, compiled via assets/css/main.scss. Uses Susy grid, Breakpoint mixins, Font Awesome + Academicons icon fonts.

JavaScript: jQuery-based. Source in assets/js/_main.js, minified to assets/js/main.min.js via UglifyJS. Plugins: Magnific Popup, Greedy Navigation, Smooth Scroll, Stickyfill.

Content Authoring

Homepage is _pages/about.md (permalink: /).

Adding a publication: Create a markdown file in _publications/ with frontmatter:

title: "Paper Title"
collection: publications
permalink: /publication/YYYY-MM-DD-slug
venue: 'Conference/Journal'
paperurl: 'https://...'
date: YYYY-MM-DD
excerpt: "<img src='/images/thumbnail.png' width='70%'>"
citation: "BibTeX or formatted citation"

Adding a talk: Create a markdown file in _talks/ with frontmatter including type, venue, location, talk_url.

Markdown generators (markdown_generator/): Python scripts and Jupyter notebooks that convert TSV data files into collection markdown. publications.py reads publications.tsv, talks.py reads talks.tsv, pubsFromBib.py converts BibTeX.

Key Directories

Directory	Purpose
`_pages/`	Static pages (about, cv, publications archive, talks, teaching)
`_layouts/`	Page templates
`_includes/`	Reusable HTML components
`_sass/`	SCSS stylesheets
`assets/`	CSS, JS, and fonts
`images/`	Content images and favicons
`files/`	Downloadable files (PDFs)
`markdown_generator/`	TSV/BibTeX → markdown conversion tools
`talkmap/`	Leaflet.js geographic visualization of talks