CLAUDE.md

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

Project Overview

This is a Quarto-based marketing website for Query.Farm, documenting 20+ DuckDB community extensions and providing educational content about DuckDB. The site uses Python for data analysis and generates static content deployed to AWS S3.

Development Commands

Environment Setup

# Activate Python environment (required before running Quarto commands)
source ./python-env/.venv/bin/activate

Building & Previewing

# Preview site locally (runs on port 4200)
quarto preview

# Render full site
quarto render

Publishing

# Build and deploy to S3
./publish.sh

Note: publish.sh uses a custom Quarto CLI path at /Users/rusty/Development/quarto-cli/package/dist/bin/quarto and syncs to s3://query-farm-website/ with 15-second cache control.

Python Dependencies

The project uses Rye for Python dependency management. Dependencies are managed in python-env/pyproject.toml: - pandas, plotly, matplotlib, seaborn - for data visualization - cache3 - for caching external API calls (GitHub, DuckDB releases) - pyyaml, packaging, tabulate - for data processing - jupyter - for interactive development

Architecture

Content Organization

  • Extension documentation: duckdb_extension_*.qmd - Each of 20+ DuckDB extensions has its own page
  • Blog posts: posts/*.qmd - Educational content and announcements
  • Core pages: index.qmd, products.qmd, consulting.qmd, about.qmd, why_duckdb.qmd
  • Configuration: _quarto.yml (site structure, navigation), _brand.yml (typography), theme.scss (custom styling)

Extension Documentation Pattern

Every duckdb_extension_*.qmd file follows this structure:

  1. Frontmatter: title, description-meta, Open Graph and Twitter Card metadata, categories
  2. Introduction: Brief description mentioning Query.Farm as developer
  3. Installation: Community extension installation pattern
  4. Functions/API: Detailed function documentation with code examples
  5. Usage Examples: SQL code blocks demonstrating practical use
  6. Newsletter signup: Bootstrap card component with Buttondown form

Key conventions: - Extensions use emoji icons in titles and navigation (e.g., ✈️ airport, 🦆 bitfilters, 🔒 crypto) - SQL examples show both query and DuckDB ASCII table output format - Each extension page links to GitHub repo and DuckDB community extension page - Installation follows standard pattern: INSTALL extension_name FROM community; LOAD extension_name;

Python Code in QMD Files

Python code blocks are used for data analysis (extension availability, growth metrics, ecosystem tracking):

  • Use #| echo: false and #| output: asis for markdown table generation
  • Cache external API calls with cache3.DiskCache() to avoid rate limits and speed up renders
  • Common pattern: Clone duckdb/community-extensions repo, fetch DuckDB releases from GitHub API, check extension URLs, generate visualizations

Example from extension ecosystem analysis:

import cache3
cache = cache3.DiskCache()

# Clone community-extensions repo to list extensions
# Check platform availability: linux_amd64, osx_arm64, wasm_mvp, etc.
# Generate pandas pivot tables and plotly visualizations

Platform support varies: - Native: linux_amd64, linux_amd64_musl, linux_arm64, osx_amd64, osx_arm64, windows_amd64, windows_amd64_mingw - WebAssembly: wasm_mvp, wasm_eh, wasm_threads (fewer extensions available) - URL pattern: http://community-extensions.duckdb.org/v{version}/{platform}/{extension}.duckdb_extension.{ext}

D2 Diagrams

Some pages use the d2 Quarto filter for system architecture diagrams (see duckdb_extension_tributary.qmd, duckdb_extension_radio.qmd):

filters:
  - d2
d2:
  layout: elk
  theme: EarthTones
  theme-config:
    light:
      background: transparent
    dark:
      background: transparent

Brand & Style

  • Brand name: “Query.Farm” (capital F), or “Query Farm LLC” in legal contexts
  • Typography: Headland One for headings, Noto Sans for body, Fira Code for code (defined in _brand.yml)
  • DuckDB extensions: Lowercase in code (install crypto), Title Case in prose (“Crypto extension”)
  • Tone: Professional but accessible, developer-focused
  • Emojis: Encouraged in headings and navigation for visual identity

Key Files

  • _quarto.yml - Main site configuration with navbar, sidebar, metadata
  • _brand.yml - Typography settings
  • theme.scss - Custom CSS styling
  • publish.sh - Deployment script (custom Quarto path, S3 sync)
  • python-env/pyproject.toml - Python dependencies
  • categorize-extensions.py - Utility to clone community-extensions repo and extract metadata
  • .gitignore - Excludes _site/, .quarto/, python-env/, *.quarto_ipynb

Adding New Extension Documentation

  1. Create duckdb_extension_{name}.qmd following the standard template
  2. Add entry to _quarto.yml sidebar under “Extensions” with emoji icon
  3. Include GitHub repo and community extension links in sidebar
  4. Update products.qmd to include in categorized list if needed
  5. Follow naming convention: snake_case for files, Title Case with emoji for display

Important Notes

  • No automatic image copying: Images in images/ directory must be manually copied to _site/ (handled in publish.sh)
  • Cache management: Python code caches API responses in .mypy_cache/; clear if data seems stale
  • S3 deployment: Website uses CloudFront CDN with 15-second cache-control headers
  • Custom Quarto: Uses development build at /Users/rusty/Development/quarto-cli/ rather than system Quarto
  • Python environment: Always activate venv before running Quarto commands that execute Python code blocks

Messaging

  • Query.Farm builds DuckDB extensions (independent from DuckDB Labs)
  • 20+ extensions with millions of downloads
  • Focus areas: Community extensions, consulting services, developer tools
  • Target audience: Data engineers, analytics teams, DuckDB users