CLAUDE.md

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

Project Overview

Personal website for Kevin McNellis built with Quarto, a scientific and technical publishing system. The site focuses on policy analysis, budget process, and congressional procedure research.

Live site: https://www.kevinmcnellis.com

Commands

# Preview site locally (watches for changes)
quarto preview

# Build site (outputs to _site/)
quarto render

# Publish to GitHub Pages (manual method)
quarto publish gh-pages

Deployment: Pushes to main trigger the GitHub Actions workflow (.github/workflows/publish.yml) which renders the site and deploys to GitHub Pages.

Architecture

Content Model

Pages (.qmd files in root): Core site pages using Quarto Markdown
Posts (posts/*.qmd): Blog posts with YAML frontmatter for date, categories, etc.
Publications (publications/publications.yml): Data-driven listing of research and articles

Key Configuration

_quarto.yml: Site-wide configuration including navigation, theme, and format options
styles/sidebar.css: Custom CSS with brand colors
includes/: HTML partials for metadata and social sharing

Color Palette

Color	Hex	Usage
Primary blue	`#4355a5`	Links, active states, hover accents
Dark text	`#102a43`	Headings, titles
Body text	`#486581`	Descriptions, secondary text
Muted text	`#829ab1`	Dates, metadata
Border	`#e9ecef`	Dividers, card borders

Layout

The site uses a docked sidebar layout (not a top navbar) with: - Profile headshot as logo - Social links (LinkedIn, GitHub, Twitter, Email) - Navigation to “Writing” section (blog posts)

Content Patterns

Adding a new blog post:

# posts/YYYY-MM-DD-title.qmd
---
title: "Post Title"
description: "Brief description for listing page"
date: YYYY-MM-DD
author: "Kevin McNellis"
image: images/figure-name.png
freeze: true
---

The posts listing uses a custom EJS template (posts/listing-custom.ejs) showing title, description, and date. Images are not displayed in the listing due to legibility at thumbnail size.

Adding a publication:

# publications/publications.yml
- title: "Publication Title"
  authors: ["Kevin McNellis"]
  venue: "Journal/Blog Name"
  year: 2025
  url: "https://..."
  categories: [congress, rules]
  type: article

Gotchas

EJS Template Indentation

Quarto processes EJS templates through its markdown pipeline. HTML with 4+ spaces of indentation becomes a code block instead of rendered HTML. Keep all HTML at the left margin in .ejs files.

<!-- WRONG - will render as <pre><code> block -->
    <div class="listing-item">
        <h3>Title</h3>
    </div>

<!-- RIGHT - renders as HTML -->
<div class="listing-item">
<h3>Title</h3>
</div>

Freeze Cache

Pages with freeze: true cache rendered output in _freeze/ directory. If content changes don’t appear after rendering:

# Delete the freeze cache for a specific folder
rm -rf _freeze/<folder>/

# Then re-render
quarto render

Context Document

Context Document.md contains the original migration brief from WordPress with detailed specifications for the site redesign. Reference it for design intent and future feature plans (dark mode toggle, contact forms, etc.).