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 the Kittysplit blog (blog.kittysplit.com), a Jekyll 4.4 static site hosted on GitHub Pages. Deploying is done by pushing to the main branch.

Commands

  • Install dependencies: bundle
  • Run locally: bundle exec jekyll serve --port 3000
  • Run with drafts: bundle exec jekyll serve --drafts --port 3000
  • Generate title image: npm run generate:title -- scripts/configs/<post-slug>.json

Architecture

  • _posts/ — Published blog posts (Markdown with YAML front matter)
  • _drafts/ — Unpublished draft posts
  • _layouts/ — default.html (base), post.html, page.html
  • _includes/ — Reusable partials (analytics, social icons, twitter plug)
  • style.css / highlighting-style.css — Site styles (Sass compiled by Jekyll)
  • images/ — Post images, organized by date subdirectories (e.g., images/2026-02-11/)
  • scripts/ — Title image generator (Playwright + HTML template). Shared logo assets live in scripts/assets/, per-post configs in scripts/configs/.

Blog Post Conventions

  • Posts use the naming format YYYY-MM-DD-slug.md
  • Front matter requires layout: post and title; image is optional (used for social cards)
  • Use <!-- read-more --> to mark excerpt boundaries (configured as excerpt_separator in _config.yml)
  • Permalinks follow the /:title/ pattern
  • Date format in prose is dd.mm.YYYY (e.g. 11.03.2026)
  • Images are stored in images/<date>/ and referenced with kramdown attributes for sizing: {: width="320"}
  • Capitalisation: always capitalise Kittysplit and Kitty (the name for a shared expense group)
  • Tone: easy going and friendly — like chatting with a friend, not a press release. No corporate speak, no buzzwords. Keep it casual and genuine.
  • Structure: don’t over-structure with headers. Match the flow of existing posts.

Writing a New Post

When asked to create a new post, follow these steps in order:

  1. Research. Use WebSearch/WebFetch to gather context about the topic. Skim 2–3 posts from _posts/ dated 2024 or earlier to internalise voice and tone. If anything about the topic is unclear, ask before writing.
  2. Write. Create _posts/YYYY-MM-DD-<slug>.md using the conventions above. Front matter example: 
    ---
layout: post
title: "Your Title Here"
image: /images/YYYY-MM-DD/<name>-title.png
---
  3. Humanise. Run /humaniser on the finished draft to strip AI writing patterns. Mandatory — don’t skip.
  4. Generate the title image (see the Title Images section below). Reference it in the front matter image: and inline at the top of the body.
  5. Verify. Run bundle exec jekyll build --future and fix any errors it reports.

Title Images

Every new post gets a title image generated by scripts/generate-title-image.mjs. Do not hand-pick or reuse an image from elsewhere.

  1. Drop the post’s screenshot (e.g. a phone shot) into images/YYYY-MM-DD/.
  2. Create scripts/configs/YYYY-MM-DD-<slug>.json with this shape: 
    {
  "output": "images/YYYY-MM-DD/<name>-title.png",
  "screenshot": "images/YYYY-MM-DD/<screenshot>.png",
  "scheme": "blue",
  "slots": {
    "eyebrow": "New · <short label>",
    "title": "First line of headline,",
    "accent": "second line.",
    "subtitle": "One or two natural sentences. Avoid em dashes.",
    "url": "https://www.kittysplit.com"
  }
}

    scheme is optional — pick "blue" (indigo gradient, sky-blue accent) or "cyan" (teal gradient, orange accent). Defaults to blue.

  3. Run npm run generate:title -- scripts/configs/YYYY-MM-DD-<slug>.json.
  4. Reference the generated image in the post’s front matter (image:) and inline at the top of the body.

All paths in the config are resolved from the repo root. The template lives in scripts/title-template.html.

Plugins

  • jekyll-sitemap — Auto-generates sitemap.xml
  • jekyll-seo-tag — SEO meta tags and social cards