AGENTS.md - Academic Website Development Guide

This is Till Köveker’s academic website built on the Academic Pages Jekyll template.

Quick Facts

• Framework: Jekyll (static site generator) + Minimal Mistakes theme
• Deployment: GitHub Pages (tillkoeveker.github.io)
• Tech Stack: Ruby (Jekyll), Python (utilities), HTML/SCSS
• Configuration: _config.yml (do not auto-reload; restart server after changes)

Project Structure

Content Directories

Configuration & Layout

• _config.yml - Site-wide settings (author info, site title, collections)
• _layouts/ - HTML templates for different page types
• _includes/ - Reusable HTML components (header, footer, author profile, analytics)
• _data/ - YAML data files (navigation, UI text, authors)
• _sass/ - Stylesheets
• assets/ - Static files (CSS, JS, images)
• files/ - Downloadable files (PDFs, etc.)
• images/ - Image assets

Content Guidelines

YAML Frontmatter Structure

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

---
title: "Paper Title"
collection: publications
category: Publications
permalink: 
date: YYYY-MM-DD
authors: "Author Names (with <strong> tags for emphasis)"
venue: "Journal/Conference Name"
paperurl: "https://..."
excerpt: "Optional brief description"
---

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

---
title: "Talk Title"
collection: talks
type: "Talk"  # or "Tutorial", "Conference Presentation", etc.
permalink: /talks/YYYY-MM-DD-slug
venue: "Institution/Conference Name"
date: YYYY-MM-DD
location: "City, Country"
---

Teaching (_teaching/YYYY-MM-DD-slug.md):

---
title: "Course/Teaching Title"
collection: teaching
type: "Course"
permalink: /teaching/YYYY-MM-DD-slug
venue: "Institution Name"
date: YYYY-MM-DD
---

Running the Site

Prerequisites

• Ruby 3.2+, Bundler, Node.js (see README.md for OS-specific install instructions)
• For Linux: sudo apt install build-essential gcc make

Local Development

# Install dependencies
bundle install

# Start local server with live reload
jekyll serve -l -H localhost
# Site available at http://localhost:4000

Using Docker

# Build image
docker build -t jekyll-site .

# Run container
docker run -p 4000:4000 --rm -v $(pwd):/usr/src/app jekyll-site

Automation Utilities

Markdown Generator (markdown_generator/)

Converts TSV files to markdown frontmatter. Useful for bulk importing publications and talks from structured data.

Files:

• publications.py / publications.ipynb - Generate publication markdown from publications.tsv
• talks.py / talks.ipynb - Generate talk markdown from talks.tsv
• pubsFromBib.py - Convert BibTeX to markdown (experimental)
• OrcidToBib.ipynb - ORCID to BibTeX conversion

Usage:

• Edit the .tsv file with publication/talk metadata
• Run the Python script or Jupyter notebook
• Generated .md files appear in _publications/ or _talks/

TSV Format for Publications: pub_date, title, venue, excerpt, citation, site_url, paper_url

Talkmap (talkmap.py, talkmap.ipynb)

Generates a Leaflet cluster map of talk locations from the location: field in _talks/ markdown files.

• Extracts location from each talk’s YAML frontmatter
• Geocodes locations with Nominatim (OpenStreetMap)
• Outputs HTML/JS map to talkmap/ directory
• Dependencies: glob, getorg, geopy

Key Editing Workflows

Add a New Publication

1. Create _publications/YYYY-MM-DD-slug.md with proper frontmatter
2. Or use markdown_generator/publications.py if bulk-importing from TSV
3. Restart jekyll serve to see changes
4. Verify on https://localhost:4000/publications

Add a New Talk/Conference

1. Create _talks/YYYY-MM-DD-slug.md with proper frontmatter
2. Include location: field for talkmap support
3. Optionally run talkmap.py to regenerate map

Update Author Profile

Edit _config.yml under the author: section. Restart server after changes.

Add Static Page

1. Create .md file in _pages/
2. Set permalink: for URL slug
3. Update navigation in _data/navigation.yml if needed

File Naming Conventions

• Dated content (_publications/, _talks/, _teaching/): YYYY-MM-DD-url-slug.md
  • Date allows chronological sorting
  • Slug should be URL-friendly (lowercase, hyphens)
• Static pages (_pages/): name.md (no date prefix)
• Policy papers (_policy/): YYYY-Description-Source.md

Important Notes

⚠️ Config Changes: _config.yml changes require server restart (not auto-reloaded)

⚠️ Frontmatter is Critical: Missing or malformed YAML frontmatter will prevent pages from rendering

📌 Markdown Files: Use standard Markdown with YAML frontmatter block at the top (between ---)

📌 URLs: When linking internally, use Jekyll permalinks (e.g., /publications/2023-01-01-slug)

Further Resources

• README.md - Project setup and deployment
• Academic Pages Documentation
• Jekyll Documentation
• Minimal Mistakes Theme