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 and Discoverability

This section reflects search practice as of 2026. The short version: write genuinely useful, experience-led content for humans and structure it so both Google and AI assistants can understand and cite it. Keyword placement and density are not the game any more — topical relevance, search intent, demonstrated experience, and machine-readable structure are.

The mental model (read this first)

Two audiences now find these posts:

  1. Search engines — Google ranks on topical relevance, search intent, and E-E-A-T (Experience, Expertise, Authoritativeness, Trust). Since the Helpful Content updates (2022-24), keyword-stuffed or over-optimized content is actively demoted. BERT/MUM understand context, so you don’t need to repeat exact keywords — you need to cover the topic well and match what the reader actually wants.
  2. AI assistants — Google AI Overviews, ChatGPT, Perplexity, and Claude increasingly answer questions by summarizing and citing pages. This is Generative Engine Optimization (GEO / AEO). To get cited, content must be quotable: self-contained claims, clear definitions, comparison tables, stats with sources, and direct Q&A.

Optimize for both by being clear, concrete, accurate, and well-structured. There is no separate “SEO version” of a good technical post — the same qualities serve readers, Google, and LLMs.

E-E-A-T: lead with experience (Elton’s biggest asset)

Google added “Experience” to E-A-T in late 2022, and it’s the single strongest lever this blog has. First-hand, been-there content outranks generic explainers.

Search intent and topic coverage (replaces “keyword placement”)

Titles and meta descriptions

Structure for humans and machines

Structured data

CLAUDE.md | Elton’s Blog

` (jekyll-seo-tag) already emits the core Article JSON-LD, OpenGraph, and Twitter card metadata — make sure title, description, and header.teaser are set and it handles the rest.

Images, performance, and Core Web Vitals

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 genuinely descriptive alt text to all images — describe what the image shows for a screen-reader user. Be specific, not padded to a character count.
  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. Headings: Write the clearest heading for the reader. Do NOT inject keywords into every H2 — that’s an over-optimization signal now (see SEO and Discoverability). A descriptive heading that matches the section’s intent is enough. Only reword a heading if the original is genuinely unclear, not to fit a keyword.
  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.