CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Personal academic website for Teddy Svoronos (teddysvoronos.com), built with Jekyll and hosted on GitHub Pages. Uses the Beautiful Jekyll theme (v6.0.1). Topics: pedagogy, AI in education, teaching technology, productivity.

Build Commands

# Install dependencies
bundle install && bundle exec appraisal install

# Build site (includes future-dated posts)
bundle exec appraisal jekyll build --future

# Local development server
bundle exec jekyll serve

# Local dev with drafts and future posts
bundle exec jekyll serve --drafts --future

MCP Server (mcp-server/ directory)

cd mcp-server && npm install
npm run dev    # local development
npm run lint   # TypeScript type checking

Architecture

  • Jekyll static site with Kramdown markdown (GFM), Rouge syntax highlighting
  • Content: _posts/ (published), _drafts/ (unpublished), plus standalone .md pages at root (teaching.md, publications.md, blog.md, home.md)
  • Theme: _layouts/ (base, default, home, post, page, minimal, none), _includes/ (header, footer, nav, search, analytics components)
  • Static API: api/ directory generates JSON endpoints via Liquid templates (posts.json, pages.json, tags.json, manifest.json) with an OpenAPI 3.1.0 spec
  • MCP Server: mcp-server/ is a separate TypeScript/Node.js app deployed on Vercel that exposes blog content to Claude via the Model Context Protocol

Blog Post Format

Posts go in _posts/ with filename YYYY-MM-DD-slug.md. Frontmatter:

---
layout: post
title: 'Title'
subtitle: 'Subtitle'
author: 'Teddy Svoronos'
cover-img:
thumbnail-img:
tags:
    - Pedagogy
    - AI
---

Common tags: Pedagogy, AI, Research, Productivity, Keynote, Zoom, Presentations, Online-Teaching, iPad, Handwriting, Two-Stage-Exams, Course Corrections.

Key Configuration

  • _config.yml: Site settings, navigation, colors, analytics (Google Analytics gtag), permalink format /:year-:month-:day-:title/
  • Permalink structure: URLs like /2026-01-26-skating-to-an-erratic-puck/
  • Pagination: 5 posts per page
  • Custom domain: teddysvoronos.com (via CNAME file)
  • CI: GitHub Actions runs bundle exec appraisal jekyll build --future on push/PR with Ruby 3.3

Deployment

  • Site: Push to master branch; GitHub Pages auto-builds
  • MCP Server: Vercel auto-deploys from mcp-server/ directory