AGENTS.md / CLAUDE.md

This file provides guidance to coding assistants and agents (such as Claude Code) when working with files in this repository.

Project Overview

This is The Sprout Fund’s evergreen website, built with Jekyll and GitHub Pages. The site archives programs, projects, and grants from The Sprout Fund, a Pittsburgh-based nonprofit that supported community initiatives.

Live URL: https://www.sproutfund.org Repository: https://github.com/sproutfund/website_evergreen

Development Commands

Preferred: VS Code Devcontainer

The recommended development approach uses VS Code with devcontainers, which provides a consistent Docker-based environment. This allows you to run Jekyll in a container while using command-line claude from the host machine.

Setup:

  1. Open folder in VS Code
  2. Click “Reopen in Container” (or F1 → “Dev Containers: Reopen in Container”)
  3. Press Cmd+Shift+B / Ctrl+Shift+B to start Jekyll server
  4. Access site at http://localhost:4000/website_evergreen/

Configuration files:

Workflow benefits:

Docker Development

The project includes a comprehensive Dockerfile:

Build image:

docker build -t sproutfund-jekyll .

Run development server:

docker run --rm -it \
  -v "$(pwd):/srv/jekyll" \
  -p 4000:4000 \
  sproutfund-jekyll \
  bundle exec jekyll serve --config "_config.yml,_config_dev.yml" \
  --host 0.0.0.0 --livereload

Note: WORKDIR is set to /srv/jekyll in the Dockerfile, so volume mounts work correctly.

Local Development (Without Docker)

If developing without Docker, install dependencies locally:

# Install dependencies (requires Ruby 3.3.4 and Node.js)
bundle install
npm install

# Development server with live reload (uses both config files)
bundle exec jekyll serve --config "_config.yml,_config_dev.yml" --livereload

# Development server with incremental builds
bundle exec jekyll serve --config "_config.yml,_config_dev.yml" --livereload --incremental

# Build for development
bundle exec jekyll build --config "_config.yml,_config_dev.yml"

# Build for production
bundle exec jekyll build

Note: Both bundle install (Ruby gems) and npm install (Node.js for Lunr.js) are required.

Architecture

Content Organization

The site uses a data-driven architecture where project/grant information lives in a CSV file and is dynamically rendered into pages:

Key Directories

Configuration

Data Page Generation

The data_page_generator.rb plugin enables generating pages from CSV data:

page_gen:
  - data: "grants"            # Source: _data/grants.csv
    template: "grant"         # Layout: _layouts/grant.html
    name: "grant-id"          # Field used for URL/filename
    extension: "txt"
    filter_condition: "record['show-hide'] == 'show'"

This generates a page for each grant where show-hide == ‘show’, creating URLs like /projects/highlights/community/#project-slug.

Search Implementation

The site includes a client-side search using:

Jekyll Plugins Used

Content Structure Conventions

Program Pages (program/*.md)

Program pages use a data-driven templating system: content lives in YAML front matter, structure is defined by Liquid templates (_layouts/program.html, _includes/page_parts/*.html), and project data auto-loads from grants.csv via grant-id references.

Key front matter sections: cover-image, video, context, by-the-numbers, highlights (with nested sections and features), acknowledgements.

See FRONTMATTER_GUIDE.md for complete documentation on all fields, template mappings, data integration, and examples.

Grants CSV Structure

Key fields in _data/grants.csv:

Important Notes