CLAUDE.md

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

Project Overview

Personal academic portfolio website for Elías Cisneros (Assistant Professor, UT Dallas). Built with Jekyll using the Minimal Mistakes remote theme (mmistakes/minimal-mistakes, skin: contrast). Deployed via GitHub Pages at https://eliascis.github.io.

Ruby Setup

Homebrew is the x86_64 (Rosetta) install at /usr/local. Ruby is managed via rbenv and must be built under x86_64 to link against Homebrew libraries:

arch -x86_64 rbenv install 3.3.10
rbenv local 3.3.10
gem install bundler
bundle install

The .ruby-version file (set to 3.3.10) is committed, not gitignored — .github/workflows/build.yml reads it via ruby-version: .ruby-version, so removing or ignoring it breaks CI.

Native gem builds need an explicit -arch x86_64

Xcode 26 ships Apple clang 21 as an arm64-only binary that defaults to an arm64 target, and arch -x86_64 zsh cannot change that — there is no x86_64 clang slice to select. Against the x86_64 Ruby above, every mkmf have_func probe then fails to link libruby.3.3.dylib and silently returns no, so the gem compiles its old-Ruby/TruffleRuby fallback shims and dies with errors like static declaration of 'rb_hash_bulk_insert' follows non-static declaration.

Fix by passing the arch through to mkmf’s $ARCH_FLAG for the affected gem. Via BUNDLE_BUILD__<GEMNAME> it applies to one command only and leaves no .bundle/config behind:

BUNDLE_BUILD__JSON='--with-arch-flag="-arch x86_64"' bundle update json --conservative

Verify with file <gem>/…/*.bundle — it must report Mach-O 64-bit bundle x86_64. Before debugging a gem’s C source, check its mkmf.log for required architecture 'arm64'; that is the actual tell, since the compile error points nowhere near the cause. The durable alternative is rebuilding Ruby as arm64-native, which also means re-resolving the lockfile’s platform-specific gems (e.g. sass-embedded) and dropping the x86_64 Homebrew at /usr/local.

Development Commands

# Local development server
bundle exec jekyll serve

# Build site (output to _site/)
bundle exec jekyll build

# Minify JavaScript (only needed if modifying JS assets)
npm run build:js

# Watch JS for changes
npm run watch:js

Note: _config.yml is NOT auto-reloaded by jekyll serve — restart the server after config changes.

Architecture

• Theme: Remote theme via remote_theme: "mmistakes/minimal-mistakes" — theme files are fetched at build time, not stored locally. Local _layouts/, _includes/, and _sass/ directories contain overrides of the upstream theme.
• Content pages: _pages/ — static pages (home, research, teaching, code, blog, media, privacy policy)
• Blog posts: _posts/ — Markdown files with YAML front matter (layout: single by default)
• Collections: teaching collection is enabled with output: true
• Navigation: _data/navigation.yml — defines the main site menu (Home, CV, Research, Teaching, Code & Data, Blog)
• Assets: assets/images/ (images), assets/files/ (PDFs, course materials), assets/teaching/
• CV: Linked directly as a PDF at /assets/files/cisneros_cv.pdf (not a generated page)

Key Configuration

All in _config.yml:

• permalink: /:categories/:title/
• Markdown: kramdown with GFM
• SASS output: compressed
• Excluded from build: vendor, node_modules, z_old, code, not-posted, and various dev files
• Default front matter sets layout: single and author_profile: true for both posts and pages

Content Conventions

• Pages use permalink: in front matter to define their URL path
• Blog posts follow YYYY-MM-DD-title.md naming in _posts/
• Images for content are stored in assets/images/
• Downloadable files (PDFs, scripts) go in assets/files/