Maggie Zhang

Maggie Zhang

IS researcher. Interested in AI & Social Media

CLAUDE.md

CLAUDE.md

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

What This Is

A Jekyll-based academic personal website for Maggie Zhang, built on the Academic Pages template (itself forked from Minimal Mistakes). Deployed via GitHub Pages with custom domain drmaggiezhang.com (configured in CNAME).

Local Development

# Install dependencies (first time)
bundle install

# Serve locally with live reload
bundle exec jekyll serve -l -H localhost
# Site available at http://localhost:4000

# Alternatively, using Docker
docker compose up

If bundle install fails with permission errors, first run:

bundle config set --local path 'vendor/bundle'

Architecture

Content and configuration are fully separated:

  • _config.yml — Site-wide settings (author info, social links, publication categories, plugin config). Requires server restart when changed.
  • _data/navigation.yml — Top nav links. Currently only “CV” is active; other sections (Publications, Talks, etc.) are commented out.
  • _data/cv.json — Structured CV data used by the JSON-based CV page (/cv-json/).
  • _pages/ — Static pages (about, CV, 404, etc.). about.md is the homepage (permalink: /).
  • _publications/, _talks/, _posts/, _teaching/, _portfolio/ — Content collections. Each item is a Markdown file with YAML front matter.
  • files/ — PDFs and downloadable assets (served at /files/<filename>).
  • images/ — Site images; profile.png is the sidebar avatar.

Collections behavior

  • publications → individual pages generated (output: true)
  • teaching, portfolio, talks → no individual pages (output: false)

CV page

The CV page (_pages/cv.md) currently embeds files/Maggie_Zhang_CV___IS.pdf via an <iframe>. The JSON-driven alternative (_pages/cv-json.md) reads from _data/cv.json and can be regenerated with:

./scripts/update_cv_json.sh

Adding Content

New publication — create _publications/YYYY-MM-DD-short-title.md with front matter:

---
title: "Paper Title"
collection: publications
category: manuscripts  # or 'conferences' or 'books'
permalink: /publication/YYYY-MM-DD-short-title
excerpt: 'Brief description'
date: YYYY-MM-DD
venue: 'Journal or Conference Name'
paperurl: 'https://...'
citation: 'Author et al. (Year). ...'
---

Bulk content generation — use the Jupyter notebooks or Python scripts in markdown_generator/ to convert TSV files (talks.tsv, publications.tsv) into properly formatted Markdown files.

Theme & Layout System

The site inherits from the Minimal Mistakes theme via the github-pages gem. Key customization points:

  • _layouts/ — Page templates (e.g., single, archive, talk). Most pages use single or archive layout via front matter defaults in _config.yml.
  • _includes/ — Reusable HTML partials. author-profile.html controls the sidebar; archive-single-cv.html and archive-single-talk-cv.html render collection items on the CV page.
  • _sass/ — SCSS partials compiled by Jekyll. Modify styles here, not in generated CSS.
  • assets/css/main.scss — Entry point that imports the SCSS partials.

Enabling Nav Sections

Uncomment the relevant entries in _data/navigation.yml to add sections (Publications, Talks, Teaching, Portfolio, Blog Posts) to the top navigation.

Deployment

Push to master branch — GitHub Pages builds and deploys automatically. No CI config needed. The CNAME file maps to drmaggiezhang.com.