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 Field Guide for Philanthropy & Civic Action, built with Jekyll and GitHub Pages. The site documents best practices, lessons learned, and practical guidance for catalytic funding and community building.

Live URL: https://fieldguide.sproutfund.org Repository: https://github.com/sproutfund/field-guide

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/field-guide/

Configuration files:

Workflow benefits:

Docker Development

The project includes a comprehensive Dockerfile:

Build image:

docker build -t field-guide-jekyll .

Run development server:

docker run --rm -it \
  -v "$(pwd):/srv/jekyll" \
  -p 4000:4000 \
  field-guide-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)
bundle 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: Only bundle install is currently required. Node.js/npm support is available for future enhancements (e.g., Lunr.js search).

Architecture

Content Organization

The site uses a hierarchical content structure organized around two main program areas:

Key Directories

Configuration

Layouts and Their Purpose

The site uses specialized layouts for different content types:

  1. docs.html: Main documentation pages with sidebar navigation, table of contents, and optional templates/downloads sections
  2. experiences.html: Community building event guides with special formatting
  3. techniques.html: Facilitation technique documentation
  4. voices-from-the-field.html: Practitioner biography pages with “learn more” sidebar
  5. templates-downloads.html: Template and resource download pages
  6. home.html: Homepage layout
  7. default.html: Base HTML structure

See docs/CONTENT_GUIDE.md for complete documentation on layouts, frontmatter fields, and content structure.

Data-Driven Components

Several site features are driven by YAML data files:

See docs/DATA.md for complete documentation on data file structures and usage.

Custom Jekyll Plugins

Standard GitHub Pages Plugins

Content Structure Conventions

Documentation Pages (layout: docs)

Documentation pages use frontmatter to control navigation, display options, and dynamic content:

layout: docs
title: "Page Title"
subtitle: "Brief description"
description: "Full SEO description"
section: catalytic-funding | community-building
group: planning-preparing | cultivating-applicants | experiences | etc.
toc: true | false

Key sections within documentation pages:

Voices from the Field Pages

Biography pages for featured practitioners:

layout: voices-from-the-field
title: "Person Name"
subtitle: "Role/Title"
section: community-building
group: voices-from-the-field
voices-learn-more:
  text: "Learn more about their work"
  email: "[email protected]"
  twitter: "handle"
  website: "https://url.com"

Experiences and Techniques Pages

Community building guides with specialized formatting:

layout: experiences | techniques
title: "Experience/Technique Name"
subtitle: "Brief description"
section: community-building
group: experiences | techniques

Exporting Content for LLM Ingestion

The site includes functionality to export all content to consolidated Markdown files optimized for LLM ingestion. This is useful for creating comprehensive references or training data.

Export command:

bundle exec jekyll build --config "_config.yml,_config_export.yml"

Export files generated in _site/:

Export characteristics:

Configuration:

Important Notes

URL Structure

The site uses Jekyll’s default pretty permalinks:

Redirects from legacy URLs are managed via jekyll-redirect-from plugin using redirect_from: frontmatter.