CLAUDE.md

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

Commands

npm run serve   # Start local dev server with hot-reload
npm run build   # Build static site to _site/

No test suite is configured.

Environment Setup

Requires a .env file with Contentful credentials:

CTFL_SPACE=<space_id>
CTFL_ACCESSTOKEN=<access_token>

Architecture

Eleventy (11ty) static site driven by Contentful CMS. Content is fetched at build time from Contentful and rendered into static HTML using Liquid templates.

Data Flow

_data/*.js files fetch from Contentful at build time → Liquid templates consume the data → Eleventy outputs _site/.

• _data/index-page.js → "resources" content type (home page)
• _data/stories.js → "story" content type (ordered by creation date)
• _data/issueonecontributors.js → "contributor" content type (Issue One commissions)
• _data/about-page.js → "aboutPage" content type

Key Config: .eleventy.js

The main Eleventy config file is large (~436 lines) and contains most application logic:

• Filters: cssmin (CSS minification), hexToRgb, lookUpColour, lookUpColourBackground (color palette lookups for contributor/story theming)
• Shortcodes: Complex rendering logic for Contentful rich text — documentToHtmlString, contributorHero, contributorBody, glossaryItem, readingListItem, footer, nav, etc.
• Rich text rendering: Custom node renderers for embedded Contentful entries (audio, images, transcripts, ASCII art)
• Collections: "contributions" collection with prev/next post navigation built in

Templates

Root-level .liquid files are pages; _includes/ contains layout and shared components:

• _includes/layout.liquid — main HTML wrapper used by all pages
• stories-story.liquid — individual story pages (uses Eleventy pagination over stories data)
• chapterone.liquid — contributor listing page
• glossary.liquid — glossary and reading list page

Styling

Plain CSS, no framework. Files in _includes/:

• main.css — primary styles
• reset.css — CSS reset
• storycolors.css — per-story color theming

CSS is minified at build time via the cssmin filter.

Static Assets

src/assets/ contains static files copied to the build output. src/_redirects is a Netlify redirects file.

Image Optimization

Uses @11ty/eleventy-img for AVIF/JPEG generation; cached images land in img/ and .cache/.