UVA Math Website Content Management Guidelines

This document provides comprehensive guidelines for maintaining content on the UVA Mathematics Department website.

Common Tasks

Many content management requests come via email from department colleagues. These typically include:

Posting seminar/colloquium abstracts
Announcing conferences and workshops
Updating speaker information
Publishing award and defense announcements
Adding job postings

When processing email requests, extract the key information (speaker names, titles, abstracts, dates, locations) and format according to the guidelines below.

Content Structure

The website uses Jekyll to generate static content from markdown files. All website edits are managed through GitHub, with changes taking approximately 5 minutes to appear on the live site.

UVA arXiv Tracker

Phase 1 tracker code lives under scripts/uva_arxiv/. Keep fetched sources, SQLite caches, and generated scratch data out of git; scripts/uva_arxiv/cache/ is ignored except for .gitkeep. Manual curation files live under scripts/uva_arxiv/data/.

Role classification is front-matter-first in roles.py; directory names are only fallbacks or conflict checks. Current roster parsing in roster.py is keyed by UVA_id, not display name. Appointment history in roster_history.py uses git history plus current roster context, then applies manual appointment overrides. A display-name-only override must not replace inferred appointment intervals.

Evidence scripts produce review inputs, not accept/reject decisions. Missing Semantic Scholar/CrossRef metadata is incomplete metadata, and missing or absent UVA affiliation evidence is not a rejection reason.

Useful validation/debug commands:

python3 -m unittest discover -s scripts/uva_arxiv/tests
make uva-arxiv-check ARXIV_DB=/tmp/arxiv.sqlite ARXIV_SOURCES_DIR=/tmp/sources
make uva-arxiv-db-since-dry ARXIV_DB=/tmp/arxiv.sqlite ARGS="--limit 1"
python3 scripts/uva_arxiv/roster_history.py --dry-run --no-write --as-of YYYY-MM-DD
python3 scripts/uva_arxiv/s2_client.py smoke --id 2501.01234 --refresh
python3 scripts/uva_arxiv/crossref_client.py smoke --doi 10.xxxx/example --no-cache

Post Creation and Management

File Location

All post files must be placed in the _posts/ directory or one of its subdirectories
Subdirectories (e.g., _posts/conferences/, _posts/events/, _posts/IMS/) are for organization only and don't affect the URL structure

File Naming Convention

CRITICAL: Post filenames MUST follow this exact pattern:

YYYY-MM-DD-name-of-the-post.md

Where YYYY-MM-DD is the date the file is created (not the event date):

Examples:

Correct:

2023-11-15-announcing-upcoming-holiday-party.md (created on Nov 15, 2023)
2025-03-12-james-teaching.md (created on March 12, 2025, even if it announces a future event)
2025-04-08-AWM-mathclub-colloq.md (created on April 8, 2025, even if the colloquium is on a different date)

Incorrect:

2023-12-20-announcing-upcoming-holiday-party.md (using the future event date rather than creation date)
2025-05-17-final-exercises.md (if created before May 17, this should use the creation date instead)

Front Matter

Every post begins with YAML front matter, delimited by triple dashes (---):

---
layout: post
title: "Title of Your Announcement"
event-date: 2025-05-09 12:00:00
multi-day-event: true
comments: false
categories: news events conferences swiper-news
published: true
image: __SITE_URL__/img/news_events/example-image.jpg
image-alt: "Description of the image for accessibility"
image-tall: true
more-text: "Details and Schedule"
good-md: true
---

Required Front Matter Fields

layout: post - Always use this for announcements
title - The title displayed on both post rolls and the post page
categories - Determines where the post appears (see Categories section below)

Recommended Front Matter Fields

event-date - The actual date of the event (format: YYYY-MM-DD HH:MM:SS)
multi-day-event - Set to true for events spanning multiple days
published - Set to true by default. Set to false to hide a post completely

Optional Front Matter Fields

image - Path to the post image (use __SITE_URL__ prefix: __SITE_URL__/img/news_events/image.jpg)
image-alt - Alternative text for the image (for accessibility). If omitted, the post title is used as fallback alt text. Providing specific descriptive alt text is still recommended.
image-tall or image-wide - Add if your image has unusual dimensions
image-address - URL where clicking the image leads (defaults to post page if omitted)
more-text - Custom text for the "read more" button (defaults to "View details")
hide-this-item: true - Hides post from main page but not from category pages or all news
permalink - Custom URL for the post (default is /YYYY/MM/name-of-the-post)
good-md: true - Indicates that the markdown in the post is well-formed (affects rendering)

Content Display Controls

Carousel/Swiper: Add swiper-news category to include a post in the main page carousel (limited to 6 posts)
Featured Box: Posts with major-news that don't have swiper-news appear in a larger gray box below the carousel
Standard Display: Other posts with the news category appear in the main news grid

Post Content

Use markdown for post content
Place  to separate the excerpt (shown in list views) from full content
Include key details in the excerpt for visibility in post rolls
Add good-md: true to front matter if your post contains well-formatted markdown
Math formulas are supported using LaTeX syntax

Images

Store images in /img/news_events/ or an appropriate subfolder of /img/
Reference images with the __SITE_URL__ prefix: __SITE_URL__/img/news_events/image.jpg
For carousel/swiper posts, use an image with aspect ratio around 16:9 for best results
For the main post image, use the image front matter field
Additional images can be added manually in the post content using markdown

Combining Multiple Images

To combine multiple photos into a single wider image for carousel posts, use ImageMagick:

magick image1.png image2.png +append combined-output.png

This creates a horizontally combined image. Add image-wide: true to the front matter when using wide combined images.

Internal Links

Always use {% raw %}{{site.url}}{% endraw %} prefix for internal links instead of absolute or relative paths:

{% raw %}[Link text]({{site.url}}/path/to/page){% endraw %}

This ensures links work correctly across different environments.

People References

Finding People Files

People profile files are named by UVA computing ID (e.g., ntr2qp.md), not by person's name. To find someone's profile:

Search (grep) for their first or last name within _departmentpeople/ to locate the file
Common fields to update: personal_page, office, phone, image

Referencing People in Posts

To reference department members, use the person_info include rather than hardcoding names:

{% raw %}{% include person_info_just_name.html UVA_id="cc2wn" %}{% endraw %}

Available include formats:

person_info.html - Full name, title, email, phone
person_info_just_name.html - Just the person's name
person_info_email_only.html - Name with email
person_info_no_phone.html - Name, title, email (no phone)

Publishing Workflow

Create a new file with the correct naming convention in the appropriate subfolder
Add all required front matter with appropriate categories
Write your content, separating excerpt with 
Commit and push changes to GitHub (push immediately after committing, do NOT include AI attribution in commit messages)
Wait approximately 5 minutes for changes to appear on the live site

Page Visibility

Main Page Carousel: Shows up to 6 posts with swiper-news category
Main Page Featured Box: Shows 1 post with major-news (without swiper-news)
Main Page News Grid: Shows up to 6 regular posts with news category
All News Page: Shows all published posts regardless of category
Category Pages: Show all posts with specific categories (e.g., conferences page)

Use hide-this-item: true to hide items from the main page after they're no longer timely, while keeping them in archives.

Special Post Types

Defenses

PhD and DMP defense announcements should be created in _posts/defenses/ with format:

YYYY-MM-DD-lastname-defense.md

Example categories: categories: news events defenses

Job Postings

Job postings should be created in _posts/jobs/ with format:

YYYY-MM-DD-jobs-YYYY.md

Example categories: categories: news jobs

For more detailed documentation, see the website documentation pages.

Repository Structure Overview

This repository contains the source code for the University of Virginia Mathematics Department website (math.virginia.edu). It's a Jekyll-based static site that serves comprehensive information about the department's academic programs, people, research, and events.

Key Technology Stack

Jekyll - Static site generator that converts markdown to HTML
GitHub Pages - Hosting and deployment
Markdown - Primary content format
YAML - Configuration and structured data

Major Content Areas

News & Events (_posts/)
- Organized by type: conferences, awards, defenses, jobs, events
- Date-based naming: YYYY-MM-DD-title.md
- Categories control where posts appear on the site
People Profiles (_departmentpeople/)
- Separate folders for faculty, students, postdocs, staff
- Files named by UVA computing ID (e.g., ko5wk.md)
- Standardized profile format with front matter
Academic Programs
- undergraduate/ - Degree requirements, courses, advising
- graduate/ - PhD program, exams, funding
- seminars/ - Weekly seminar schedules
Special Programs
- IMS/ - Institute of Mathematical Sciences
- RTG_geomtop/ - NSF-funded Research Training Group
- awm/ - Women in Mathematics chapter
- drp/ - Directed Reading Program
- mathcircle/ - K-12 outreach
Data Files (_data/)
- courses.yml - Course catalog
- seminars.yml - Seminar configurations
- research_areas.yml - Research group definitions

Content Management Patterns

Posts must include front matter with title, categories, and layout
Internal links use {% raw %}{{site.url}}{% endraw %} prefix
People references use include files rather than hardcoded names
Categories determine post visibility on different pages
Changes take ~5 minutes to appear on live site after GitHub commit

Dark Mode Implementation

The website features a comprehensive dark mode that automatically adapts to user preferences and can be manually toggled.

Key Features

Automatic OS Detection: The site respects the user's operating system dark mode preference on first visit
Manual Toggle: Users can override the OS preference using a toggle button in the navbar
Persistent Preference: User's choice is saved in localStorage and persists across sessions
Smooth Transitions: All color changes animate smoothly when switching themes

Toggle Button Design

Location: Main navbar, positioned to the left of "Support us" link
Mobile: Remains visible on small screens, positioned to the left of the vertical dots menu on special pages
Design: Dual-icon toggle showing both cloud-sun (day) and moon (night) icons with a sliding indicator
Interaction: Click anywhere on the button to toggle between light and dark modes

Technical Implementation

CSS Architecture

The dark mode uses CSS custom properties (variables) defined in /css/main.css:

:root {
  --bg-color: #ffffff;
  --text-color: #212529;
  --card-bg: #ffffff;
  /* ... other light mode variables */
}

[data-theme="dark"] {
  --bg-color: #0a1628;  /* Very dark navy blue */
  --text-color: #e8e8e8;
  --card-bg: #1a2a3f;  /* Dark navy blue */
  /* ... other dark mode variables */
}

Color Scheme

The dark mode uses a sophisticated navy blue color palette aligned with UVA branding:

Background: #0a1628 (very dark navy)
Cards/Panels: #1a2a3f (dark navy)
Hover States: #243448 (slightly lighter navy)
Active States: #003d7a (UVA blue variation)
Text: #e8e8e8 (light gray)
Links: #4da3ff (lighter blue for contrast)

JavaScript Functionality

Located in _includes/footer.html, the dark mode script:

Checks localStorage for saved preference
Falls back to OS preference if no saved preference
Applies theme by setting data-theme attribute on <html>
Handles toggle button clicks
Listens for OS theme changes (respects if user hasn't manually set preference)

Component-Specific Styling

Navigation

Navbar: Background remains light with adjusted toggle button colors
Hamburger/Dots: Icons turn light gray (#e8e8e8) in dark mode
Dropdowns: Dark backgrounds with appropriate contrast

Sidebars

List Groups: Dark gray (#243448) backgrounds instead of white
Orange Headers: Adjusted orange tones for visibility
Active Items: UVA blue variation (#003d7a) for selected items

Content Areas

Cards: All use dark navy backgrounds
Jumbotrons: Special handling for major-news sections
Zebra Striping: Alternating rows use darker navy (#162133)
Code Blocks: Dark backgrounds with syntax highlighting

Forms

Search Bar: Semi-transparent backgrounds with light borders
Input Fields: Dark backgrounds with light text
Buttons: Appropriate contrast adjustments

Best Practices for Content Creators

Images: Ensure images have sufficient contrast for both light and dark modes
Colors: Avoid hardcoding colors in inline styles; use CSS classes instead
Backgrounds: Test content visibility in both modes before publishing
Icons: Use Font Awesome icons which automatically adapt to the theme

Testing Dark Mode

To test dark mode functionality:

Click the toggle button in the navbar
Check that all text remains readable
Verify interactive elements maintain proper contrast
Ensure images and media display correctly
Test on both desktop and mobile devices

Accessibility (WCAG 2.1 AA)

The website follows WCAG 2.1 AA accessibility standards. All new content and components must maintain these patterns.

Skip Navigation

Every layout includes a skip-to-content link as the first child of <body>:

<a href="#main-content" class="skip-link">Skip to main content</a>

The primary content area is wrapped in <main id="main-content">. The .skip-link class in css/main.css makes the link visually hidden until focused.

Visually Hidden Text

Use Bootstrap 5's visually-hidden class (not the older sr-only) to hide text that should only be read by screen readers:

<span class="visually-hidden">Description for screen readers</span>

A fallback definition exists in css/main.css in case Bootstrap's class is unavailable.

ARIA Labels

All icon-only links (social media, etc.) must have aria-label describing the link purpose
Navigation landmarks (<nav>) must have unique aria-label values to distinguish them (e.g., "Main navigation", "Social media", "Undergraduate program")
The search form uses role="search" and aria-label="Site search"
The dark mode toggle uses aria-pressed to convey its state

Focus Indicators

Never suppress focus outlines on interactive elements for keyboard users. The site uses visible focus indicators that meet 3:1 contrast ratio in both light and dark modes. Do not add outline: none, box-shadow: none, or the shadow-none class to buttons, links, or form controls unconditionally. If mouse-click focus rings need to be suppressed for aesthetic reasons, use the :focus:not(:focus-visible) pattern to preserve keyboard focus indicators.

Carousel Accessibility

The main page Swiper carousel includes:

A pause/play toggle button with dynamic aria-label
Previous/next navigation buttons
Keyboard navigation support
Automatic pause when prefers-reduced-motion: reduce is active

Reduced Motion

The site respects prefers-reduced-motion: reduce via a media query in css/main.css that disables transitions and animations. The carousel autoplay is also disabled for users who prefer reduced motion.

Uh oh!

FilesExpand file tree

CLAUDE.md

Latest commit

History