AGENTS.md

Project Overview

This is an Academic Pages Jekyll portfolio website hosted on GitHub Pages. It uses the academicpages.github.io template, forked from the Minimal Mistakes Jekyll theme.

Author: Ruixin Zhan, Master’s candidate at Northeastern University (China)
Live URL: https://ZhanRuiXin.github.io

Build & Development

Local Development (Ruby/Jekyll)

# Install dependencies
bundle install

# Run live-reload server (refreshes on .md/.html changes only)
jekyll serve -l -H localhost

# Alternative with bundle exec
bundle exec jekyll serve -l -H localhost

Note: Changes to _config.yml require restarting the server.

Local Development (Docker)

docker compose up
# Access at http://localhost:4000

VS Code DevContainer

Open in DevContainer (F1 → “DevContainer: Reopen in Container”) for automatic local hosting at http://localhost:4000.

JavaScript Build

npm install
npm run build:js  # Minifies JS to assets/js/main.min.js

Content Collections

Content is organized into Jekyll collections in underscore-prefixed directories:

Collection	Directory	URL Prefix	Purpose
Posts	`_posts/`	`/posts/YYYY/MM/slug/`	Blog posts
Publications	`_publications/`	`/publication/YYYY-MM-DD-slug`	Academic papers
Talks	`_talks/`	`/talks/YYYY-MM-DD-slug`	Presentations/lectures
Teaching	`_teaching/`	`/teaching/YYYY-MM-DD-slug`	Teaching experience
Portfolio	`_portfolio/`	`/portfolio/N`	Project showcases

Frontmatter Conventions

Posts (_posts/YYYY-MM-DD-title.md):

---
title: 'Post Title'
date: YYYY-MM-DD
permalink: /posts/YYYY/MM/slug/  # Optional
tags:
  - tag1
  - tag2
---

Publications (_publications/YYYY-MM-DD-slug.md):

---
title: "Paper Title"
collection: publications
category: conferences  # books | manuscripts | conferences
permalink: /publication/YYYY-MM-DD-slug
excerpt: 'Brief description'
date: YYYY-MM-DD
venue: 'Venue Name'
paperurl: 'URL to paper PDF'
citation: 'Formatted citation'
---

Talks (_talks/YYYY-MM-DD-slug.md):

---
title: "Talk Title"
collection: talks
type: "Talk"  # Talk | Workshop | etc.
permalink: /talks/YYYY-MM-DD-slug
venue: "Venue Name"
date: YYYY-MM-DD
location: "City, Country"
---

Configuration

_config.yml: Main site configuration (author info, URL, theme, navigation settings)
_config_docker.yml: Docker-specific overrides
_data/navigation.yml: Header navigation links (commented = hidden)
_data/authors.yml: Author profiles
_data/ui-text.yml: UI text strings (localization)

Localization

The theme supports English (en) and Chinese (zh) via lang frontmatter. Chinese-specific fields are prefixed with zh_ (e.g., zh_title, zh_bio).

English pages: /publications/, /about.md
Chinese pages: /publications-zh.html, /about-zh.md

Static Assets

Files/PDFs: Place in files/ → accessible at /files/filename.pdf
Images: Place in images/ for posts, assets/ for site-wide assets

Key Files

File	Purpose
`_layouts/`	Page templates (single, archive, cv, talk, etc.)
`_includes/`	Reusable HTML snippets (author profile, head, footer, etc.)
`_sass/`	SCSS stylesheets with theme variables
`_pages/`	Static pages (about, cv, publications, talks, teaching)
`talkmap/`	Interactive talk map (Plotly-based)

Common Pitfalls

Jekyll rebuild: Changes to _config.yml or _layouts/ require server restart, not just live reload
Permalink format: Publications use /publication/YYYY-MM-DD-slug while posts use /posts/YYYY/MM/slug/
Categories: Publication categories must match keys in _config.yml under publication_category (books, manuscripts, conferences)
File naming: Posts and collection items require YYYY-MM-DD- prefix in filename

Ruixin Zhan