CLAUDE.md
# CLAUDE.md
This file provides context and conventions for AI assistants working in this repository.
## Overview
This is a personal academic website for Ayal Chen-Zion, an economist. It is a **Jekyll static site** hosted on **GitHub Pages** at `achenzion.github.io`. The site showcases research papers, blog posts, teaching experience, and software resources.
## Tech Stack
- **Static site generator**: Jekyll (via `github-pages` gem)
- **Hosting**: GitHub Pages (auto-deploys from `master` branch on push)
- **CSS framework**: GitHub Primer (loaded via CDN in `assets/styles.scss`)
- **Plugins**: `jekyll-github-metadata` (GitHub API data), `jekyll-octicons` (SVG icons)
- **Templating**: Liquid (Jekyll's default)
- **Stylesheet**: SCSS (`assets/styles.scss` + `_sass/_highlight-syntax.scss`)
- **No JavaScript** — entirely static HTML/CSS
## Repository Structure
```
.
├── _config.yml # Jekyll site configuration (layout, style, projects, social)
├── Gemfile # Ruby gem dependencies
├── index.html # Homepage (uses 'home' layout)
├── favicon.ico
│
├── _layouts/ # Page layout templates
│ ├── default.html # Base layout with optional sidebar
│ ├── home.html # Homepage layout (includes all sections)
│ └── post.html # Blog post layout
│
├── _includes/ # Reusable Liquid components
│ ├── header.html # meta tags, CSS, dark/light mode
│ ├── footer.html # Page footer
│ ├── masthead.html # Profile sidebar (avatar, bio, links, social icons)
│ ├── projects.html # GitHub repos section (reads from GitHub API)
│ ├── research.html # Research posts section (tag: research)
│ ├── thoughts.html # Blog posts section (tag: blog)
│ ├── interests.html # Topics/interests section (from _config.yml)
│ ├── post-card.html # Blog post card component
│ ├── repo-card.html # Repository card component
│ └── topic-card.html # Interest/topic card component
│
├── _data/
│ ├── colors.json # Programming language → color mappings (for repo cards)
│ └── social_media.yml # Social network definitions (icons, URL templates)
│
├── _posts/ # Blog and research posts
│ └── YYYY-MM-DD-title.{html|md}
│
├── _sass/
│ └── _highlight-syntax.scss # Code block syntax highlighting
│
├── assets/
│ └── styles.scss # Main stylesheet (imports Primer CSS + custom styles)
│
├── pdfs/ # PDF documents
│ ├── ChenZion_Resume.pdf
│ ├── ChenZion_Resume.tex
│ └── research/ # Research paper PDFs
│ └── teaching/ # Teaching statement PDFs
│
├── research/index.html # Research page (filters posts by tag: research)
├── teaching/index.html # Teaching page (static HTML)
├── thoughts/index.html # Resources hub page
│ ├── economics/index.html
│ └── software/index.html
```
## Local Development
```bash
# Install dependencies
bundle install
# Serve locally with live reload
bundle exec jekyll serve
# Site available at http://localhost:4000
# Note: "No GitHub API authentication" warning is expected and harmless
```
After changing `_config.yml`, restart the server (`Ctrl+C`, then re-run) — Jekyll does not hot-reload config changes.
## Deployment
Pushing to the `master` branch automatically triggers GitHub Pages to rebuild and deploy the site. No CI/CD pipeline or manual build step is required.
## Content Conventions
### Blog Posts and Research Papers
All content lives in `_posts/` with filename format:
```
YYYY-MM-DD-title.html (preferred — most existing posts use HTML)
YYYY-MM-DD-title.md (also supported)
```
All posts **default to the `post` layout** via `_config.yml` defaults — no need to specify `layout` in front matter.
**Front matter fields:**
```yaml
---
title: "Post Title"
published: true # false to draft/hide; omit to default true
tag: # used to filter posts into sections
- research # appears in research.html include
- blog # appears in thoughts.html include
# also: economics, software, privateSector
status: "Journal, Month Year" # publication status for research posts
coauthors: # HTML links to co-author pages (for research posts)
- Name and
- Name
---
```
- Use `tag: research` for academic papers; use `tag: blog` for blog posts.
- Research posts show at most 6 in the homepage section (`research.html` limit).
- Blog posts show at most 12 in the homepage section (`thoughts.html` limit).
- The `privateSector` tag is used on the research page to distinguish academic vs. private sector work.
### Pages
Static pages (e.g. `research/index.html`, `teaching/index.html`) use the `default` layout and filter `site.posts` by tag using Liquid:
```liquid
{% for post in site.posts %}
{% if post.tag contains 'research' %}
...
{% endif %}
{% endfor %}
```
## Configuration (`_config.yml`)
Key settings:
| Setting | Current Value | Notes |
|---|---|---|
| `layout` | `sidebar` | Two-column on desktop. Change to `stacked` for single-column. |
| `style` | `light` | White/gray background. Change to `dark` for dark theme. |
| `projects.sort_by` | `pushed` | Sort repos by last push. Alternative: `stars`. |
| `projects.limit` | `5` | Number of repos shown on homepage. |
| `projects.exclude.forks` | `true` | Forked repos are hidden. |
| `resume` | `/pdfs/ChenZion_Resume.pdf` | Linked from masthead. |
To add social media links, uncomment the relevant lines under `social_media:` and provide the username/ID.
To enable the "My Interests" section, add entries under `topics:` with `name`, `web_url`, and `image_url`.
## Styling
- **Primer CSS** is imported from CDN in `assets/styles.scss` — do not copy it locally.
- Custom styles go in `assets/styles.scss` after the Primer import.
- Syntax highlighting styles are in `_sass/_highlight-syntax.scss`.
- The site uses Primer utility classes extensively (e.g. `col-12`, `col-md-8`, `p-3`, `bg-gray`).
## Key Patterns
### Adding a Research Paper
1. Create `_posts/YYYY-MM-DD-Paper-Title.html`
2. Use front matter: `tag: [research]`, `status:`, `coauthors:` (see above)
3. Write abstract in `
` tags 4. Link to publication and/or PDF ### Adding a Blog Post 1. Create `_posts/YYYY-MM-DD-Post-Title.html` or `.md` 2. Use front matter: `tag: [blog]`, `published: true` ### Adding a New Static Page 1. Create `page-name/index.html` (or `page-name.html` at root) 2. Front matter: `layout: default`, `title: "Page Title"` 3. Accessible at `/page-name/` ### Updating the Resume Replace `pdfs/ChenZion_Resume.pdf`. The `.tex` source is also in `pdfs/` for editing. ## What Not to Change - `_data/colors.json` — large auto-generated language color map; leave as-is unless updating language colors. - `_data/social_media.yml` — social network definitions; only modify to add new networks, not to change personal usernames (those go in `_config.yml`). - The Primer CSS CDN import in `assets/styles.scss` — the HTML uses many Primer utility classes that would break without it. ## Branch Convention - `master` — production branch; pushes deploy immediately to GitHub Pages - Feature branches for staged changes before merging to `master`