CLAUDE.md

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

Project Overview

XCH.farm is a Jekyll static site serving as a resource hub for Chia cryptocurrency farming. It provides educational content, interactive calculators, and data visualizations. Deployed to GitHub Pages at xch.farm.

Build Commands

bundle install              # Install Ruby dependencies
bundle exec jekyll serve --livereload   # Local dev server with hot reload
bundle exec jekyll build    # Production build to _site/
bundle exec jekyll clean    # Remove _site/ and .jekyll-cache/

No test suite or linter is configured.

Architecture

Layout Pipeline

Every page uses layout: default which composes: top.html (head/opening body) → header.html (nav sidebar) → page content → footer.html → bottom.html (scripts/closing body).

Page Structure

Pages are standalone HTML files at the repo root with Jekyll front matter:

  • layout: default, title, permalink are required
  • js_files lists page-specific JS from assets/js/pages/
  • selected_categories filters FAQ/glossary content on some pages

Key Directories

  • _data/ — YAML data files driving navigation (navbar.yml), calculator presets (presets.yml), FAQ, glossary, and hero content
  • _includes/ — Reusable HTML partials (top, bottom, header, footer)
  • assets/js/pages/ — Page-specific JavaScript (calculators, charts, simulators)
  • assets/js/data/ — Auto-generated JSON data (daily-wins.js updated by CI)
  • assets/libs/ — Vendored client libraries (Chart.js, Choices.js, Toastify)
  • _scripts/ — Python scripts for fetching blockchain data. fetch_netspace_data.py is the main entry point, backed by lib/ shared modules (constants, API, data I/O). Scripts use only stdlib (urllib.request) — no external Python dependencies required.

Calculator/Tool Pattern

Each tool page (calculator, time-to-win, simulator, etc.) has a corresponding JS module in assets/js/pages/. Calculator presets are defined in _data/presets.yml. Chart pages use Chart.js for visualizations with data from assets/js/data/.

Styling

Bootstrap-based with custom CSS. Uses Remix Icon and Boxicons for icons.

CI/CD

Weekly update (.github/workflows/weekly-netspace-update.yml) runs every Saturday:

  1. Fetches GH wins, NoSSD wins (CoinSet API), and netspace (SpaceFarmers API) in separate steps
  2. Each step can fail independently; successful steps are cached in assets/js/data/_cache/
  3. Merges caches into assets/js/data/daily-wins.js and creates a PR

Backfill (.github/workflows/backfill-netspace.yml) is manually triggered with date range and mode inputs.

Running locally:

cd _scripts
python3 fetch_netspace_data.py --mode gh --start-date 2026-04-18 --end-date 2026-04-19
python3 fetch_netspace_data.py --mode nossd --start-date 2026-04-18 --end-date 2026-04-19
python3 fetch_netspace_data.py --mode netspace --start-date 2026-04-18 --end-date 2026-04-19
python3 fetch_netspace_data.py --mode merge

Modes: gh, nossd, netspace, all, merge. NoSSD processes one day at a time with per-day caching for resilience.

Adding a New Page

  1. Create your-page.html at repo root with proper front matter
  2. Add page-specific JS to assets/js/pages/ if needed
  3. Add entry to _data/navbar.yml in the appropriate section