CLAUDE.md

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

Project Overview

ActualPlay.Network is a static site generator project built with Eleventy (11ty) v2.0. It's a podcast/RPG blog converted from WordPress, featuring episodes organized by game systems with audio playback, RSS feeds, and metadata-driven navigation.

Development Commands

Core Commands

• npm run start / npm run serve – Start development server with live reload (http://localhost:8080)
• npm run watch – Watch mode without server (useful for background work)
• npm run build – Production build (sets ELEVENTY_ENV=production, outputs to _site/)
• npm run debug – Debug mode with verbose output (DEBUG=* eleventy)

All commands automatically set ELEVENTY_ENV to either development or production. The dev server includes BrowserSync auto-reload with a custom 404 middleware.

Project Structure

actualplay.11ty/
├── _data/                  # Global data files
│   └── metadata.json       # Site-wide metadata (title, feeds, author)
├── _includes/              # Template partials and layouts
│   ├── layouts/            # Post, home, new-listener layouts
│   ├── components/         # Reusable components (audio-box, system-list, article-footer)
│   └── postslist.njk       # Posts collection template
├── posts/                  # Podcast episodes (markdown with YAML frontmatter)
├── pages/                  # Static pages (contact, resources, biographies)
├── feed/                   # Feed templates (RSS, JSON, Podcast)
├── css/                    # Stylesheets (passthrough copy)
├── js/                     # JavaScript assets (passthrough copy)
├── img/                    # Images (passthrough copy)
├── archive.njk             # Tags/archive page
├── categories.njk          # System categories page
└── _site/                  # Build output (ignored by git)

Key 11ty Configuration

Defined in .eleventy.js:

• Template Formats: Markdown, Nunjucks, HTML, Liquid
• Plugins:
  • eleventy-plugin-rss – Feed generation
  • eleventy-navigation – Navigation hierarchy
• Collections:
  • systems – Aggregated game systems from posts with counts (sorted by frequency)
  • tagList – Tags excluding metadata tags (all, nav, post, posts)
• Custom Filters:
  • readableDate() – Formats dates as "dd LLL yyyy"
  • htmlDateString() – ISO format for HTML date inputs
  • head(n) – Get first n items from array
  • min() – Find minimum value
  • threeThouStrSlice() – Truncate to 3000 chars (RSS workaround)
  • inspect() – Debug filter (logs to console)

Content Authoring

Posts (Episodes)

Located in posts/ as .md files with YAML frontmatter:

---
title: Episode Name
description: Long description
date: YYYY-MM-DD
tags: [Tag1, Tag2, Podcast]
audio: https://...     # Audio file URL
duration: "H:MM:SS"
size: 66824611         # File size in bytes
type: audio/mpeg       # MIME type
image: https://...     # Cover image
permalink: slug/       # Custom URL slug
layout: layouts/post.njk
systems: [FATE, DeltaGreen]  # Game systems played
---

Content here...

Pages

Static pages in pages/ with frontmatter. Use layout: layouts/new-listener.njk or layouts/base.njk.

Important Metadata

metadata.json contains:

• Site title, URL, description
• Feed configuration (RSS, Podcast RSS, JSON Feed)
• Author info (name, email, URL)

Update the author block and feed paths if needed; the podcast feed pulls from posts with audio or simplecastembedcodesrc fields.

Collections & Filtering

• All Posts: Collections filtered to items with data.audio or data.simplecastembedcodesrc
• Systems Collection: Built from systems array in post frontmatter; used on categories page
• Tags: Filtered via tagList collection, excluding metadata tags

Tags in posts use tags: array in frontmatter.

Special Notes

• The site filters posts to only include episodes with audio for podcast feeds and system aggregation
• threeThouStrSlice filter exists because some RSS readers have 3000-char limits
• EditorConfig enforces 2-space indentation across all files
• BrowserSync in dev mode serves 404.html for all non-existent routes (useful for SPA-style development)
• Template engine mapping: Markdown → Liquid, HTML → Nunjucks