CLAUDE.md

CLAUDE.md

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

Project Overview

This is a Jekyll-based personal website deployed to GitHub Pages at nathan-delacretaz.com. The site uses a custom theme with dark mode support and handles content data via CSV files with UTF-8 encoding safeguards.

Development Commands

Local Development

# Recommended Docker approach
docker run --rm -it -p 4000:4000 -v "$PWD":/usr/src/app -w /usr/src/app jekyll/jekyll:latest jekyll serve --host 0.0.0.0 --force_polling

# Using convenience script
./dev-server.sh


# Ruby/Jekyll directly
bundle install
bundle exec jekyll serve

Build Commands

# Build for production
bundle exec jekyll build

# Build with drafts and future posts
bundle exec jekyll serve --drafts --future

Deployment

The site deploys automatically to GitHub Pages via GitHub Actions:

  • Production: https://nathan-delacretaz.com (custom domain)
  • GitHub Pages: https://nathandela.github.io/own_website/
  • Auto-deploys on push to main branch

Architecture

Jekyll Structure

  • _layouts/: Page templates (default.html, page.html, post.html)
  • _data/: Data files, primarily stolen_content.csv with UTF-8 handling
  • _sass/: Sass stylesheets with compressed output
  • assets/: Static assets including CSS and JavaScript for filtering and theme toggle
  • _thinks/: Think posts with permalink structure /think/:title/

Data Management

The site uses CSV files for content data with built-in UTF-8 encoding protection:

  1. Source: Edit _data/stolen_content.csv directly
  2. UTF-8 Protection: Git pre-commit hook automatically cleans CSV files (removes BOM, fixes encoding)
  3. Jekyll Integration: Jekyll reads CSV data directly using configured CSV reader

Theme and Features

  • Custom navigation defined in _config.yml
  • Dark mode toggle functionality via JavaScript
  • Tag filtering system for content
  • RSS feed via jekyll-feed plugin
  • SEO optimization with jekyll-seo-tag
  • Responsive design with custom CSS

Key Files and Locations

Configuration

  • _config.yml: Site configuration, navigation, collections, and CSV reader settings
  • Gemfile: Dependencies including github-pages and jekyll plugins
  • .github/workflows/deploy.yml: GitHub Actions deployment configuration

Data Management

  • _data/stolen_content.csv: Primary content data source (edit directly)
  • .git/hooks/pre-commit: Automatic UTF-8 cleaning for CSV files

Templates and Styling

  • _layouts/default.html: Main page template with navigation and theme toggle
  • assets/css/main.scss: Main stylesheet compiled from _sass directory
  • assets/js/: JavaScript for filtering, theme toggle, and sharing functionality

Development Workflow

Think Content Workflow

  1. Create Posts: Add new posts directly in _thinks/ directory
    • Use frontmatter: layout, title, date, type, tags
    • Files are automatically published at /think/:title/ permalinks
    • All posts in _thinks/ are live on the site

Content Data Workflow

  1. Data Updates: Edit _data/stolen_content.csv directly
  2. UTF-8 Safety: Pre-commit hook automatically cleans encoding issues
  3. Content Updates: Edit markdown files directly
  4. Styling: Modify files in _sass/ directory
  5. Testing: Use bundle exec jekyll serve with automatic reload
  6. Production: GitHub Pages builds automatically on push to main branch

Dependencies

  • Ruby and Bundler
  • Jekyll and github-pages gem
  • Docker (optional but recommended for consistent environment)

Important Notes

  • CSV files are automatically cleaned for UTF-8 compliance via git pre-commit hook
  • Navigation is controlled via _config.yml navigation array
  • The site excludes certain directories from processing (node_modules, vendor, etc.)
  • Dark mode state is managed client-side with JavaScript
  • RSS feed is available at /feed.xml