akisonlyforu

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 hosted on GitHub Pages. The site features blog posts, portfolio content, book reviews, and personal information. The architecture follows Jekyll’s conventions with custom collections and layouts.

Development Commands

Installation

bundle install

Local Development

bundle exec jekyll serve

This starts a local development server, typically at http://localhost:4000, with auto-regeneration enabled.

Building for Production

The site is automatically built and deployed by GitHub Pages when changes are pushed to the master branch.

Architecture & Structure

Content Organization

  • collections/_posts/ - Technical blog posts in markdown format with YAML frontmatter
  • collections/_thoughts/ - Personal musings and reflections (displayed as “Musings” on site)
  • collections/_portfolio/ - Portfolio items and projects
  • interview/ - Interview prep resources with subsections (Data Structures, System Design, Low Level Design, Multithreading)

Layout System

  • _layouts/ - Jekyll layout templates (default.html, post.html, page.html, post-wide.html, about.html)
  • _includes/ - Reusable template components (navigation.html, footer.html, head.html, header.html, share_buttons.html, subscribe.html, pagination.html)
  • _sass/ - Sass stylesheets for styling (29 SCSS partials: 18 root-level + 11 in basscss/ subdirectory)
  • css/ - Compiled CSS output

Configuration

  • _config.yml - Main Jekyll configuration with site settings, plugins, and collections
  • Gemfile - Ruby dependencies including github-pages, jekyll-feed, jekyll-seo-tag, jekyll-sitemap, and webrick
  • Collections are defined in _config.yml under collections: with custom output settings

Data Files

  • _data/books.yaml - Book collection data
  • _data/library.yaml - Reading library data
  • _data/antilibrary.yaml - Antilibrary (unread books) data
  • _data/bookmarks.json - Curated bookmarks collection
  • _data/goodreads_library_export.csv - Goodreads reading data export

Other Notable Files

  • ads.txt - Google AdSense publisher verification
  • feed.xml - RSS feed (custom template including posts and thoughts)
  • 404.md - Custom 404 error page
  • DEVELOPMENT.md - Development setup documentation
  • RECAPTCHA_SETUP.md - reCAPTCHA configuration guide

Major Features & Implementation

Homepage & Navigation

  • Responsive tile-based homepage (index.md) with 3-column grid layout
  • Fixed navigation with mobile hamburger menu (_includes/navigation.html)
  • JavaScript-powered menu toggle with smooth animations
  • Current page highlighting and dropdown support

Interview Prep

  • Interview preparation hub (/interview/index.html) with topic cards
  • Four subsections: Data Structures, System Design, Low Level Design, Multithreading
  • Navigation dropdown menu provides direct access to each subsection

Search System

  • Client-side search functionality (search.html, search.json, search/js/search.js)
  • Weighted scoring system: Title (3pts), Summary (2pts), Body (1pt)
  • Real-time search with URL parameter support (?q=searchterm)
  • Debug mode enabled for localhost development

Contact & Social Integration

  • Google Apps Script-powered contact form (contact.md, assets/js/contact.js)
  • Async form handling with loading states and success/error messaging
  • Social media links with Font Awesome icons (in _includes/footer.html)
  • Support for GitHub, Twitter, LinkedIn, email, RSS, and donation platforms
  • Share buttons on posts (_includes/share_buttons.html): Twitter, LinkedIn, Facebook, Email, Copy Link
  • Clipboard API with fallback for copy-link; per-platform GA tracking; guarded by site.show_sharing_icons

Newsletter / Subscribe

  • Substack-powered email subscription CTA (_includes/subscribe.html)
  • Email validation, loading states, and success/error messaging
  • GA event tracking for subscription actions
  • Substack URL configured in _config.yml

Content Management

  • Blog pagination (12 posts per page) with 47 existing posts
  • Custom collections system for posts, thoughts, and portfolio
  • Portfolio items use post-wide layout for visual projects
  • Categories and tags for content organization
  • Search functionality supports both posts and thoughts collections

Styling & Assets

  • Modular SCSS architecture with 31 SCSS partials in _sass/ (20 root-level + 11 in basscss/)
  • Dark mode support with theme toggle (_sass/_dark-mode.scss, assets/js/dark-mode.js)
  • Cache-busting with timestamp queries for CSS and JS files
  • Font optimization (Inter, Source Code Pro) with preloading
  • Responsive design with mobile-first approach
  • CSS variables for theming throughout the codebase

Performance & SEO

  • Google Analytics integration with gtag
  • Open Graph and Twitter Card metadata
  • Canonical URLs and meta descriptions
  • DNS prefetching for external resources
  • Instant.page preloading for faster navigation
  • AnchorJS for automatic heading anchors
  • jekyll-seo-tag plugin for automatic structured data and meta tags
  • Google AdSense integration (configured in _config.yml, ads.txt for publisher verification)

Dynamic Features

  • Daily rotating philosophical quotes in footer (44 quotes, primarily from Jordan Peterson’s 12 Rules for Life)
  • Date-based quote selection for consistency across visits
  • Mobile-responsive hamburger menu with smooth animations
  • Instant.page preloading for faster page transitions

Bookmarks System

  • Curated bookmarks page (/bookmarks/index.html)
  • Data stored in _data/bookmarks.json
  • Categories for organizing links

Reading Collection

  • Library page (pages/reading/library.md) - Books read
  • Antilibrary page (pages/reading/antilibrary.md) - Books to read
  • Data sourced from YAML files in _data/

Content Guidelines

  • Blog posts use frontmatter with layout, title, date, summary, and categories
  • File naming convention: YYYY-MM-DD-title.md for posts
  • Categories and tags are used for content organization
  • Images stored in images/ directory
  • Assets (JS, CSS) in respective js/ and css/ directories

GitHub Pages Compatibility

The site uses the github-pages gem to ensure compatibility with GitHub Pages hosting. All plugins and configurations are restricted to what GitHub Pages supports natively.

Important Implementation Details

Search System Architecture

The search system (search.html, search.json, search/js/search.js) uses client-side JavaScript with a weighted scoring algorithm:

  • Fetches all content from /search.json at page load
  • Combines posts and thoughts collections into a single searchable array
  • Title matches score 3 points, summary matches 2 points, body matches 1 point
  • Supports URL query parameters (?q=searchterm) for direct search links
  • Debug logging enabled for localhost development

Contact Form Integration

The contact form uses Google Apps Script as a backend:

  • Form action points to a Google Apps Script web app endpoint
  • Uses reCAPTCHA v3 for spam protection
  • Async submission with loading states and feedback messages
  • No server-side code required in this repository
  • RSS feed (feed.xml) includes both posts and thoughts collections

Analytics System

Enhanced analytics tracking (assets/js/analytics.js) beyond basic Google Analytics:

  • Page view tracking with content category and type metadata
  • Reading progress tracking on blog posts (25%, 50%, 75%, 100% scroll milestones)
  • External link click tracking via beacon transport
  • Social media click tracking (Twitter, LinkedIn, GitHub, Substack)

Theme System

Dark mode implementation uses:

  • CSS custom properties (variables) defined in SCSS files
  • data-theme attribute on root element to toggle themes
  • JavaScript in assets/js/dark-mode.js handles theme switching and persistence
  • Theme preference stored in localStorage

The fixed navigation bar (_includes/navigation.html):

  • Uses Liquid templating to highlight current page
  • Mobile hamburger menu with JavaScript toggle functionality
  • Dropdown menu actively used for Interview section with 4 subsections
  • CSS handles both desktop and mobile layouts with media queries