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 data blog focused on social media analytics and Buffer data insights. The project generates a static website with data analysis posts that include R code, visualizations, and insights about posting frequency, engagement, and social media behavior.

Project Structure

  • _quarto.yml: Main Quarto configuration defining website structure, theme (darkly), and navbar
  • posts/: Individual blog posts, each in its own directory with index.qmd and associated data files
  • _freeze/: Quarto’s computational cache containing executed R code results and generated plots
  • _site/: Generated static website output (published to Netlify)
  • _publish.yml: Deployment configuration for Netlify hosting
  • *.rds: R data files containing cached analysis results and datasets

Core Workflow Commands

Building and Previewing

# Render the entire site
quarto render

# Preview site locally with live reload
quarto preview

# Render specific post
quarto render posts/post-name/index.qmd

Running R Code

# Execute R commands directly
Rscript -e "command_here"

# Run R script file
Rscript script_name.R

# Check R environment and packages
Rscript -e "sessionInfo()"

Publishing

# Publish to Netlify (configured in _publish.yml)
quarto publish netlify

Content Creation Workflow

Creating New Posts

  1. Create new directory in posts/ with descriptive name
  2. Add index.qmd with YAML frontmatter including:
    • title, author, date
    • categories for post classification
    • image for post thumbnail
    • format.html.code-fold: true to fold R code by default
  3. Include R code chunks for data analysis
  4. Save intermediate data as .rds files for performance

Data Analysis Pattern

Posts typically follow this structure: - Load required packages (buffer, dplyr, ggplot2, etc.) - Load or query data (often from BigQuery) - Perform analysis with R code - Generate visualizations - Save results as .rds files for reuse

Important Configuration

Computational Caching

  • freeze: true is set in posts/_metadata.yml to cache computational results
  • This prevents re-running expensive BigQuery operations and R analyses
  • Delete specific cache files in _freeze/ to force re-computation

Code Folding

  • R code blocks are set to fold by default (code-fold: true)
  • This keeps posts readable while preserving code accessibility

Data Dependencies

External Data Sources

  • BigQuery: Primary data source for Buffer analytics
  • R packages: buffer, bigrquery, tidyverse, ggplot2, ggthemes, scales, lubridate, fixest
  • Authentication: BigQuery requires proper authentication setup (bq_auth())

Cached Data Files

  • .rds files contain pre-processed datasets and analysis results
  • Common files: follower data, posting frequency data, time series data
  • These files enable fast rendering without re-querying databases

Development Notes

R Environment

  • Uses R for all data analysis and visualization
  • Key libraries: buffer (internal), dplyr, ggplot2, bigrquery
  • Statistical analysis with packages like fixest, broom

Content Guidelines

  • Posts focus on Buffer’s social media data insights
  • Include methodology explanations and statistical analysis
  • Visualizations use consistent theming (ggthemes, custom styling)
  • Each post should be self-contained with cached data

Performance Considerations

  • Use freeze: true to avoid re-computation during development
  • Cache expensive operations as .rds files
  • Large datasets should be pre-processed and saved locally