CLAUDE.md - AI Assistant Guide for davrandom.github.io

This document provides comprehensive guidance for AI assistants working with this codebase.

Project Overview

This is a personal blog and portfolio website built with Jekyll and hosted on GitHub Pages. The site belongs to Davide Scaini and covers topics including programming, physics, acoustics, motorcycle travels, and DIY projects.

Key Technologies:

Jekyll static site generator (GitHub Pages compatible)
Ruby/Bundler for dependency management
Kramdown for Markdown processing with GFM (GitHub Flavored Markdown) input
Rouge for syntax highlighting
Sass for CSS preprocessing
Liquid templating engine

Site URL: davrandom.github.io

Repository Structure

davrandom.github.io/
├── _config.yml              # Jekyll configuration (site settings, navigation, plugins)
├── Gemfile                  # Ruby dependencies (uses github-pages gem)
├── Gemfile.lock             # Locked dependency versions
├── _posts/                  # Blog posts (dated files: YYYY-MM-DD-title.{md,html})
│   └── en/                  # English language posts subdirectory
├── _drafts/                 # Draft posts (not published)
│   └── mydsmv_backup/       # Backup directory
├── _layouts/                # Page layouts
│   ├── default.html         # Base layout template
│   ├── post.html            # Blog post layout
│   ├── page.html            # Simple page layout
│   ├── page_w_picture.html  # Page layout with featured image
│   └── tag_index.html       # Tag archive page layout
├── _includes/               # Reusable components
│   ├── head.html            # HTML head section
│   ├── header.html          # Site header/navigation
│   ├── footer.html          # Site footer
│   ├── scripts.html         # JavaScript includes
│   ├── tagsforpost.html     # Tag display component
│   ├── disqus.html          # Comments integration
│   └── google_analytics.html # Analytics tracking
├── _sass/                   # Sass partials
│   ├── _base.scss           # Base styles
│   ├── _layout.scss         # Layout styles
│   └── _syntax-highlighting.scss # Code syntax highlighting
├── _plugins/                # Jekyll plugins (Ruby)
│   └── _tag_gen.rb          # Tag page generator
├── assets/                  # Static assets
│   ├── css/                 # Compiled CSS
│   ├── js/                  # JavaScript files
│   ├── img/                 # Image assets
│   └── scss/                # Additional Sass files
├── css/                     # Main CSS directory
├── images/                  # Site images (used in posts/pages)
├── index.html               # Homepage (recent posts with pagination)
├── about.md                 # About page
├── archive.md               # Post archive page
├── tag.md                   # Tags index page
├── moto.md                  # Motorcycle-related content page
├── loudspeakers.md          # Speaker/audio-related content page
├── feed.xml                 # RSS/Atom feed
├── config.rb                # Compass configuration (if used)
└── .github/
    └── dependabot.yml       # Automated dependency updates (Bundler)

Development Workflow

Local Development Setup

# Install dependencies
bundle install

# Build and serve locally (default port 4000)
bundle exec jekyll serve

# Build with drafts visible
bundle exec jekyll serve --drafts

# Build for production
bundle exec jekyll build

Deployment

This is a GitHub Pages site. Deployment happens automatically when changes are pushed to the master branch. GitHub Pages builds and serves the site automatically.

Working with Posts

Post File Naming Convention

Posts MUST follow this naming pattern:

_posts/YYYY-MM-DD-title-with-hyphens.{md,html}

Examples:

_posts/2018-6-20-Use-tensorflow-to-calculate-gradients.md
_posts/2016-08-03-Updated-gems-broken-jekyll.md

Post Front Matter

Required and common front matter fields:

---
layout: post                  # REQUIRED: Use 'post' layout
title: Your Post Title        # REQUIRED: Post title
category: memo programming    # Optional: Space-separated categories
comments: true                # Optional: Enable Disqus comments (default: false)
image: filename.jpg           # Optional: Featured image (from /images/)
---

Post Content Guidelines

Markdown Format: Use GitHub Flavored Markdown (GFM)
Code Blocks: Use fenced code blocks with language specifiers:
```
```python
# Your code here
```
```
Images: Reference images from /images/ directory:
```
![Alt text](/images/image-name.jpg)
```
Internal Links: Use site-relative paths with baseurl:
```
/path/to/page/
```

Drafts

Place draft posts in _drafts/ directory
Drafts don’t require dates in filename
View drafts locally with --drafts flag
Move to _posts/ with proper date when ready to publish

Working with Pages

Page Types

Simple Pages: Use layout: page front matter
Pages with Images: Use layout: page_w_picture front matter

Navigation is configured in _config.yml:

navigation:
 - title: Home
   url: /index.html
 - title: About
   url: /about/index.html

To add a new page to navigation, add it to this list.

Styling & Assets

Sass Architecture

Partials in _sass/ are imported into main stylesheets
Use _base.scss for foundational styles
Use _layout.scss for layout-specific styles
Syntax highlighting styles in _syntax-highlighting.scss

Adding Images

Post/Page Images: Place in /images/ directory
Asset Images: Place in /assets/img/ directory
Reference in posts/pages using absolute paths from root

JavaScript

JavaScript files are in /assets/js/ and included via _includes/scripts.html.

Plugins & Custom Functionality

Tag Generator Plugin

Location: _plugins/_tag_gen.rb

What it does:

Automatically generates individual tag pages for all tags used in posts
Creates pages at /tag/[tag-name]/ for each unique tag
Uses tag_index.html layout

Configuration in _config.yml:

tag_page_layout: tag_page
tag_page_dir: tag
tag_permalink_style: pretty

Usage in Posts: Tags are defined in front matter as space-separated categories or tags.

Other Jekyll Plugins

Configured in _config.yml:

plugins: [jekyll-paginate, jemoji]
paginate: 5
paginate_path: "blog/page:num/"

jekyll-paginate: Enables pagination (5 posts per page)
jemoji: Enables GitHub emoji support

Building & Testing

Automated Testing

GitHub Actions workflows automatically test changes:

Jekyll Build Test: Runs on all PRs and pushes to master
Security Audit: Runs daily to check for vulnerabilities
Dependency Updates: Runs weekly to keep dependencies current

See .github/workflows/README.md for details on each workflow.

Before Committing Changes

Build locally to check for errors:
```
bundle exec jekyll build
```
Serve locally to preview:
```
bundle exec jekyll serve
```
Check for common issues:
- Verify post filenames follow date convention
- Ensure YAML front matter is valid
- Check that all image references are correct
- Test internal links

Note: The Jekyll Build Test workflow will automatically check your changes when you create a PR.

Dependency Updates

Automated Updates: GitHub Actions workflows handle dependency updates:

Update Dependencies workflow: Runs weekly (Mondays 9 AM UTC)
- Automatically updates dependencies
- Tests Jekyll build
- Creates PR with changes
- Can be triggered manually for immediate updates
Security Audit workflow: Runs daily
- Monitors for vulnerabilities
- Creates issues when found
- Auto-closes when resolved

Dependabot: Also configured for weekly updates (backup system)

Manual Updates: Run bundle update locally when needed

Security Note: See SECURITY_UPDATE_GUIDE.md for detailed information about:

Current vulnerability status
How to update dependencies to fix security issues
Compatibility with GitHub Pages
Post-update testing checklist
GitHub Actions workflows usage

Git Workflow

Branch Strategy

master: Production branch (auto-deploys to GitHub Pages)
claude/[task]-[id]: Feature branches for AI assistant work

Branch Naming Convention

When working as an AI assistant, use branches prefixed with claude/:

claude/add-new-post-XyZ123
claude/fix-styling-AbC456
claude/update-about-page-DeF789

Commit Messages

Follow these conventions:

Use imperative mood (“Add feature” not “Added feature”)
Keep first line under 70 characters

Include session URL at end:

Add comprehensive CLAUDE.md documentation

https://claude.ai/code/session_XXXXX

Push Protocol

Always push to feature branches:

git push -u origin claude/branch-name

Never force push to master unless explicitly requested.

Key Conventions for AI Assistants

DO:

Read existing posts before creating new ones to match style and formatting
Follow naming conventions strictly for posts (YYYY-MM-DD-title.md)
Test locally before committing if possible
Use proper front matter with all required fields
Reference the tag system when creating posts with categories
Maintain consistent markdown formatting (GFM)
Check for broken links when modifying pages
Update navigation in _config.yml when adding new top-level pages
Use existing layouts rather than creating new ones
Respect the multilingual structure (English posts in _posts/en/)

DON’T:

Don’t modify _config.yml without explicit request
Don’t remove existing posts without confirmation
Don’t change the site structure (directory layout) without discussion
Don’t add new plugins without verifying GitHub Pages compatibility
Don’t modify Gemfile unless handling dependency updates
Don’t commit large binary files (images > 1MB should be discussed)
Don’t break pagination by removing paginate-related code
Don’t remove the Disqus integration without explicit request
Don’t modify the tag generator plugin unless fixing a bug
Don’t push directly to master - use feature branches

Code Style:

HTML/Liquid: 2-space indentation
YAML: 2-space indentation, use spaces not tabs
Markdown: Standard GFM formatting
Ruby: 4-space indentation (for plugins)
Sass/CSS: 2-space indentation

Content Guidelines:

Posts are personal and technical in nature
Topics include: programming, physics, motorcycles, audio/acoustics, DIY
Mix of Italian and English content (recent posts tend to be English)
Code examples should be complete and runnable when possible
Technical accuracy is important - this is a scientist’s blog

Special Files to Note:

about.md: Contains CV, publications, patents - keep updated carefully
moto.md: Motorcycle-related content page
loudspeakers.md: Audio/speaker projects page
feed.xml: RSS feed - don’t modify unless fixing feed issues

Troubleshooting Common Issues

Jekyll Won’t Build

Check YAML front matter syntax (must have opening/closing ---)
Verify post filename follows YYYY-MM-DD format
Check for liquid syntax errors in templates
Ensure all includes are properly closed

Styling Not Appearing

Verify Sass files compile correctly
Check browser console for CSS loading errors
Ensure asset paths are correct (use site.baseurl when needed)

Tags Not Generating

Verify _tag_gen.rb plugin is present and executable
Check that tag_index.html layout exists
Ensure tags are properly formatted in post front matter

Pagination Not Working

Verify jekyll-paginate is in plugins list
Check paginate value in _config.yml
Ensure pagination code exists in index.html

Additional Resources

Jekyll Documentation: https://jekyllrb.com/docs/
GitHub Pages Documentation: https://docs.github.com/en/pages
Kramdown Syntax: https://kramdown.gettalong.org/syntax.html
Liquid Template Language: https://shopify.github.io/liquid/

Last Updated: 2026-02-06 Maintained for: AI Assistant workflows with this repository

/dav/random