Skip to content

README.md

Latest commit

 

History

History
308 lines (229 loc) · 10.4 KB

README.md

File metadata and controls

308 lines (229 loc) · 10.4 KB
Raw

Theory And Practice

Kyle Cranmer's personal website, built with Pelican.

Live site: https://theoryandpractice.org

Migration from Pelican 3.7 to 4.11

This repository is a fresh migration of the original TheoryAndPractice repository, which used Pelican 3.7.1. The migration was performed in December 2025 to modernize the site infrastructure.

Key Changes in Migration

  • Pelican version: 3.7.1 → 4.11.0
  • Environment management: Now uses pixi for reproducible environments
  • Plugin system: Migrated to Pelican 4's namespace plugin architecture where possible
  • Deployment: GitHub Actions workflow deploys to cranmer/cranmer.github.io

What Was Preserved

  • All existing content and URL structure
  • pelican-bootstrap3 theme with Bootswatch 'flatly' styling
  • Custom per-page JavaScript and CSS functionality
  • Jupyter notebook embedding via liquid tags
  • BibTeX bibliography support

Development

Prerequisites

Install pixi:

curl -fsSL https://pixi.sh/install.sh | bash

Local Development

# Build the site
pixi run build

# Serve locally with auto-rebuild
pixi run serve

# Clean output directory
pixi run clean

# Build for production
pixi run publish

# Update citation counts from OpenAlex/Semantic Scholar
pixi run update-citations

The local server runs at http://localhost:8000

Deployment

The site is deployed automatically via GitHub Actions when pushing to the main branch.

How It Works

  1. Push to main triggers .github/workflows/deploy.yml
  2. GitHub Actions builds the site using publishconf.py
  3. Output is pushed to the cranmer/cranmer.github.io repository
  4. GitHub Pages serves the site at theoryandpractice.org

Deploy Key Setup

The workflow uses a deploy key to push to the external repository:

  • Generate an SSH key pair
  • Add the public key as a deploy key (with write access) to cranmer/cranmer.github.io
  • Add the private key as a secret named DEPLOY_KEY to this repository

Plugins

Namespace Plugins (via pip)

These are installed from PyPI and auto-discovered by Pelican:

Plugin Purpose
pelican-render-math LaTeX math rendering
pelican-liquid-tags Liquid template tags (notebook embedding, etc.)
pelican-i18n-subsites Internationalization support
pelican-neighbors Next/previous article navigation
pelican-sitemap XML sitemap generation
pelican-jupyter Jupyter notebook support
pelican-presentations Presentations page from YAML data

Search

The site uses Pagefind for fast, client-side search:

  • Indexes all pages at build time
  • Instant search with no server required
  • Search icon in navbar links to /search.html

Pagefind runs automatically after Pelican builds (configured in pyproject.toml).

Local Plugins (in plugins/)

These are custom or modified plugins maintained locally:

pelican_javascript

Allows per-article/page custom JavaScript and CSS via metadata:

JavaScripts: custom.js, https://example.com/lib.js
Stylesheets: custom.css

pelican-cite

Inline BibTeX citations with [@citation-key] syntax. Generates a bibliography section at the end of articles.

Modifications made:

  • Added Bootstrap modal popup for viewing BibTeX entries
  • Added "Copy to Clipboard" functionality
  • BibTeX entries display with proper formatting

pelican-bibtex

Generates a publications page from a BibTeX file.

Modifications made:

  • Bootstrap modal for BibTeX display (replacing broken popup windows)
  • Copy to clipboard functionality
  • Handles missing journal and booktitle fields gracefully

Theme

The site uses pelican-bootstrap3 with the Bootswatch 'flatly' theme.

Theme Modifications

  • Added extra_stylesheets block for per-page CSS
  • Added per-page JavaScript support in article/page templates
  • Added Bluesky social icon (custom CSS with SVG, since Font Awesome 4.x lacks it)
  • Added publications.html template for bibliography page
  • Added presentations.html template for talks/presentations page with video icons

pelican-selected-publications

A custom plugin (in plugins/pelican-selected-publications) that generates a curated publications page organized by research themes. See the plugin README for full documentation.

Features:

  • YAML-driven category organization with BibTeX keys
  • Filter by category, year, and highlighted papers
  • Sort by category, date, or citation count
  • Publication metrics display (total papers, citations, h-index)
  • Profile icons linking to Google Scholar, INSPIRE, arXiv, OpenAlex, ORCiD
  • Citation counts fetched from OpenAlex (with Semantic Scholar fallback)
  • Collapsible Altmetric badges for each publication
  • BibTeX modal with copy-to-clipboard

Configuration:

SELECTED_PUBLICATIONS_SRC = 'content/selected-publications.yml'

# Aggregate metrics (displayed in two boxes)
ALL_PUBLICATION_METRICS = {
    'total_publications': 1200,
    'total_citations': 349000,
    'h_index': 241,
}
SMALL_AUTHOR_METRICS = {
    'total_publications': 119,
    'total_citations': 14000,
    'h_index': 41,
}

PUBLICATION_PROFILES = (
    ('Google Scholar', 'http://scholar.google.com/...', 'google-scholar'),
    ('INSPIRE', 'https://inspirehep.net/...', 'inspire'),
    ...
)

Updating Citation Counts:

pixi run update-citations

This fetches citation counts from OpenAlex (with Semantic Scholar as fallback) and saves them to content/citations.json. Manual overrides can be added to content/citations-manual.json.

pelican-collaborators

A custom plugin (in plugins/pelican-collaborators) that generates a collaborators/team page with photos organized by category. See the plugin README for full documentation.

Features:

  • YAML-driven configuration (content/collaborators.yml)
  • Category grouping (students, postdocs, scientists, collaborators)
  • Current/Former filtering with JavaScript toggle
  • Auto-fetch avatars from GitHub and Bluesky
  • Rich metadata (roles, affiliations, thesis info, current positions)
  • Automatic sorting (active first, then by year)

Configuration:

COLLABORATORS_SRC = 'content/collaborators.yml'
DIRECT_TEMPLATES = [..., 'collaborators']

Helper Scripts:

# Update start_year/end_year from co-authored publications
pixi run update-collaborator-years

# Preview changes without modifying
pixi run update-collaborator-years --dry-run

The script searches OpenAlex and INSPIRE to find co-authored papers and automatically sets collaboration date ranges.

pelican-projects

A custom plugin (in plugins/pelican-projects) that generates a projects page with card-based layout organized by category. See the plugin README for full documentation.

Features:

  • YAML-driven configuration (content/projects.yml)
  • Category grouping (software, research, methodology, community, etc.)
  • Card and list view toggle
  • Status filtering (All / Active / Completed)
  • Draft mode with separate preview page (/projects-draft.html)
  • Auto-fetch images from GitHub repos
  • SVG images get white background automatically
  • Featured projects highlighted with star badge

Configuration:

PROJECTS_SRC = 'content/projects.yml'
DIRECT_TEMPLATES = [..., 'projects', 'projects-draft']

Usage:

  • /projects.html - Main projects page (in navigation), shows only published projects
  • /projects-draft.html - Preview page (not in navigation), shows all projects including drafts

pelican-media

A custom plugin (in plugins/pelican-media) that generates a media & outreach page with embedded videos, podcasts, articles, and interviews. See the plugin README for full documentation.

Features:

  • YAML-driven configuration (content/media.yml)
  • Category grouping (videos, podcasts, articles, interviews, outreach)
  • Card and list view toggle
  • Category and year filtering
  • Embedded YouTube/Vimeo videos
  • Featured items highlighted
  • Helper script to search for new media mentions

Configuration:

MEDIA_SRC = 'content/media.yml'
DIRECT_TEMPLATES = [..., 'media']

Helper Script:

# Search Google News for new media mentions
pixi run search-media

# With options
python scripts/search_media.py --days 60 --output suggestions.yml

pelican-presentations

A custom plugin (in separate repository ../pelican-presentations) that generates a presentations page from YAML data, compatible with the IRIS-HEP presentations format.

Features:

  • Parses YAML files with presentation data (title, date, meeting, location, URL, video)
  • Groups presentations by year
  • Shows video camera icon for presentations with recordings
  • Supports both single file (PRESENTATIONS_SRC) and multiple files (PRESENTATIONS_YAML_FILES)

Configuration:

PRESENTATIONS_SRC = 'content/presentations.yml'
DIRECT_TEMPLATES = [..., 'presentations']

Configuration

  • pelicanconf.py - Development configuration
  • publishconf.py - Production configuration (extends pelicanconf.py)

Key Settings

Setting Value Purpose
SITEURL https://theoryandpractice.org Production URL
THEME themes/pelican-bootstrap3 Bootstrap 3 theme
BOOTSTRAP_THEME flatly Bootswatch theme variant
CC_LICENSE CC-BY-NC Creative Commons license
PUBLICATIONS_SRC content/kyle-20authors.bib BibTeX file for publications
PRESENTATIONS_SRC content/presentations.yml YAML file for presentations

Content Structure

content/
├── pages/           # Static pages (Home, Research, Projects, etc.)
├── images/          # Image assets
├── css/             # Custom stylesheets
├── js/              # Custom JavaScript
├── downloads/       # Downloadable files and notebooks
└── *.md             # Blog posts

License

Content is licensed under Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0).