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 blog using the Minimal Mistakes theme, hosted on GitHub Pages. The blog belongs to Elton Stoneman, a freelance IT consultant and trainer.

Key Commands

Local Development Setup

# Install Ruby dependencies (first time setup)
bundle install

# Start local Jekyll server
bundle exec jekyll serve

# Build the site
bundle exec jekyll build

The local site runs at http://localhost:4000

Ruby Environment Setup (macOS)

If Ruby environment needs to be set up:

brew install chruby ruby-install xz
ruby-install ruby 3.1.3
echo "source $(brew --prefix)/opt/chruby/share/chruby/chruby.sh" >> ~/.zshrc
echo "source $(brew --prefix)/opt/chruby/share/chruby/auto.sh" >> ~/.zshrc
echo "chruby ruby-3.1.3" >> ~/.zshrc
gem install jekyll bundler

Architecture and Structure

Content Organization

Blog Post Format

Posts use Jekyll’s naming convention: YYYY-MM-DD-title.markdown

Required front matter:

---
title: 'Post Title'
date: 'YYYY-MM-DD HH:MM:SS'
tags:
- tag1
- tag2
description: Brief description
header:
  teaser: /content/images/path/to/image.png
---

Theme Configuration

Key Features

Development Notes

Image Handling

Deployment

The blog uses a dual-environment deployment strategy with GitHub Actions:

Production Environment:

Staging Environment:

Testing Commands:

# Test production build locally
bundle exec jekyll serve

# Test staging build locally
bundle exec jekyll serve --config _config.yml,_config_staging.yml

See DEPLOYMENT.md for detailed branching strategy and setup instructions.

The blog uses a redirect system for managing external links, especially for tracking and updating affiliate links.

How It Works

  1. Define redirects in _data/redirects.yml
  2. Run ./generate-redirects.ps1 to create redirect pages
  3. Use short URLs like /l/ps-istio in your posts
  4. Commit both the YAML file and generated pages

Adding New Redirects

Edit _data/redirects.yml:

# Set the default URL for redirects without specific URLs
default_url: https://app.pluralsight.com/profile/author/elton-stoneman

- slug: my-link         # becomes /l/my-link
  url: https://...      # destination URL (optional - uses default_url if empty)
  description: ...      # optional, for reference

Then run: ./generate-redirects.ps1

Default URL Fallback: If a redirect has no url specified (or empty url:), it will automatically redirect to the default_url. This is useful for dead links or courses that are no longer available.

Benefits

UI/UX Customizations

Theme Override Approach

The blog uses the Minimal Mistakes theme. Customizations are made through:

Key UI Customizations

Homepage Layout (60/40 split):

Individual Post Hero Images:

Content Images:

Mobile Sidebar (Critical fixes for <1024px):

Typography Standards:

Hidden Elements:

CSS Organization

SEO Best Practices

Meta Descriptions

Image Optimization

Title Optimization

Internal Linking

Content Structure

Writing Style and Content Guidelines

Writing Style

Tone and Voice:

Structure and Formatting:

Technical Approach:

Unique Elements:

Content Patterns

Topics and Audience:

Post Structure:

Formatting Standards:

Recent Content Optimizations (2025-07)

Custom Styling for Text Wrapping

Problem Solved: Code blocks containing long text prompts were causing horizontal scrolling, making them hard to read on mobile.

Solution Implemented: Created a custom .prompt-wrap CSS class in assets/css/main.scss:

.prompt-wrap {
  background-color: #f8f8f8;
  border: 1px solid #e1e4e8;
  border-radius: 6px;
  padding: 16px;
  margin: 1em 0;
  font-family: 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, Courier, monospace;
  font-size: 14px;
  line-height: 1.45;
  white-space: pre-wrap;
  word-wrap: break-word;
  overflow-wrap: break-word;
}

Usage: Wrap long text content (like AI prompts or conversational examples) in <div class="prompt-wrap">content</div> instead of markdown code blocks to ensure proper text wrapping.

Content Enhancement Workflow

SEO Optimization Process:

  1. Alt Text: Add descriptive alt text to all images (150+ characters recommended)
  2. Meta Descriptions: Update to match content changes (conductor → director metaphor updates)
  3. Spelling Check: Run comprehensive spell check, common issues found:
    • “knowledgable” → “knowledgeable”
    • “prduct” → “product”
    • “Clkaude” → “Claude”
    • Possessive “it’s” vs “its”
  4. Heading Enhancement: Add targeted keywords to H2 headings for better SEO
    • Example: “Multitask Like a Manager” → “Run Multiple Claude Instances: Multitask Like a Manager”
  5. Internal Linking: Use Jekyll permalink format without dates: /post-slug/ not /2025/07/10/post-slug/

Content Publishing Workflow

Draft to Publication Process:

  1. Content creation and revisions in _drafts/filename.markdown
  2. SEO optimization (alt text, meta descriptions, spell check)
  3. Final review and date update in frontmatter
  4. Move to _posts/YYYY-MM-DD-filename.markdown for publication
  5. Update CLAUDE.md with any new learnings or patterns

AI-Related Content Best Practices

For Claude Code/AI Development Posts:

Problem: External links and redirects opened in the same tab, causing readers to navigate away from blog posts.

Solution Implemented: Added automatic new-tab opening for external links and redirects:

CSS Visual Indicators (assets/css/main.scss):

/* External links and redirects visual indicator */
.page__content a[href^="http"]:not([href*="blog.sixeyed.com"]),
.page__content a[href^="https"]:not([href*="blog.sixeyed.com"]),
.page__content a[href^="/l/"] {
  &::after {
    content: " ↗";
    font-size: 0.8em;
    opacity: 0.6;
    margin-left: 0.2em;
  }
}

JavaScript Implementation (assets/js/external-links.js):

document.addEventListener('DOMContentLoaded', function() {
  const externalLinks = document.querySelectorAll('.page__content a[href^="http"]:not([href*="blog.sixeyed.com"]), .page__content a[href^="https"]:not([href*="blog.sixeyed.com"]), .page__content a[href^="/l/"]');
  
  externalLinks.forEach(link => {
    link.setAttribute('target', '_blank');
    link.setAttribute('rel', 'noopener noreferrer');
  });
});

Configuration (_config.yml):

footer_scripts:
  - /assets/js/external-links.js

Opens in New Tab:

Stays in Same Tab:

Benefits

Hero Image Optimization (January 2025)

Hero Image Display Fix

Problem: Hero images in individual posts were being cropped vertically with object-fit: cover, forcing images to fill container horizontally.

Solution: Updated CSS to preserve aspect ratio and only resize when necessary:

.page__hero-img {
  max-width: 100%;
  height: auto;
  max-height: 350px;
  object-fit: contain;  // Changed from 'cover'
  display: block;
  margin: 0 auto;
}

.page__hero {
  border-radius: 8px;
  box-shadow: 0 4px 12px rgba(0,0,0,0.1);
  text-align: center;  // Center smaller images
  // Removed: overflow: hidden (was causing cropping)
}

Image Behavior

This ensures hero images look as intended without unwanted cropping.