CLAUDE.md

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

Development Commands

# Install dependencies
bundle install

# Serve locally (http://localhost:4000)
bundle exec jekyll serve

# Serve with incremental builds
bundle exec jekyll serve --incremental

# Include future-dated posts
bundle exec jekyll serve --future true --incremental

The JEKYLL_GITHUB_TOKEN environment variable (personal access token with public_repo scope) is required for the jekyll-github-metadata plugin, which powers the “Suggest an edit” links on posts.

Branch & PR Workflow

Never commit directly to main. All changes must go through a branch and pull request:

git checkout -b my-branch-name
# make changes
git add <files>
git commit -m "descriptive message"
git push -u origin my-branch-name
# then open a PR targeting main

Assign PRs to @w0ger for review.

Linting & Spell Check

GitHub Actions runs these on push/PR to main. To run locally:

markdownlint _posts
cspell _posts/**/*.md

Markdownlint Rules (.markdownlint.json)

cSpell Custom Words

Technical terms, proper nouns, and domain-specific words live in cSpell.json under the words array. Add new words there when the spell checker flags legitimate content.

# Check a specific file
cspell --config ./cSpell.json --no-progress "path/to/file.md"

Architecture

This is a Jekyll personal blog using the Minimal Mistakes remote theme (mmistakes/[email protected], skin: air), hosted on GitHub Pages at rogernoden.com.

Content

Post Frontmatter

All posts use this frontmatter template. Fields marked with * are required:

---
title: "Post Title Here"          # *
comments: true                    # * always true for posts
tags:
  - Tag One
  - Tag Two
date: 2026-04-21 00:00:00.000000000 -05:00   # * include timezone offset
excerpt: >-
  A one-to-two sentence summary shown in post listings. Can wrap
  across lines using YAML block scalar syntax.
header:
  teaser: images/filename.jpg     # relative to site root, no leading slash
  overlay_image: images/filename.jpg
  overlay_filter: 0.5             # typically 0.5 for readability
  caption: >-
    Photo by [**Photographer Name**](https://unsplash.com/@handle)
    on [**Unsplash**](https://unsplash.com/photos/photo-slug)
categories:
  - Technology                    # broad; see existing posts for conventions
  - Development
---

layout: single and classes: wide are set globally in _config.yml defaults — do not repeat them in post frontmatter.

read_time: true, related: true, show_date: true, and author_profile: true are also set globally and should be omitted from individual posts.

Project Frontmatter

Projects differ from posts — no date, no comments, and external image URLs are supported:

---
title: Project Name
layout: single
excerpt: Brief description &mdash; HTML entities are fine here.
header:
  teaser: https://external-url.com/image.png
  overlay_image: https://external-url.com/project-header.png
---

comments: false and no read_time are set globally for projects in _config.yml.

Pages

Static pages in _pages/ use layout-specific frontmatter:

Layout Used for Notes
splash Home page Uses feature_row for grid sections
posts Blog index Minimal frontmatter; posts auto-populated
collection Projects index entries_layout: grid for card view
tags Tags archive Auto-populated by Jekyll
categories Categories archive Auto-populated by Jekyll
single About, other pages Standard single-column layout

Image Conventions

Theme Customization

The site overrides specific Minimal Mistakes components rather than forking the theme:

Configuration

_config.yml is the primary configuration file. Key sections:

_data/navigation.yml controls the top nav links (Blog, Projects, About). _data/ui-text.yml contains multilingual UI strings for 30+ languages — rarely needs editing.

VS Code Setup

.vscode/blog-snippets.code-snippets defines a pimg snippet for Markdown files. Type pimg and press Tab to expand:

![alt text](/images/posts//filename.jpg)

.vscode/settings.json configures markdownlint to match the project’s .markdownlint.json rules (H1 and trailing-punctuation rules disabled).

GitHub Actions

.github/workflows/housekeeping.yml runs on every push or PR to main:

Job Tool Target
Markdown linting avtodev/markdown-lint:v1 (Docker) _**/*.md
Spell checking cSpell via Node.js 18 **/*.md

Both jobs must pass before merging. Run them locally (see Linting section) before pushing to avoid CI failures.

Dependabot is configured (.github/dependabot.yml) to keep GitHub Actions dependencies up to date.