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 static site for random.qmx.me, deployed via GitHub Pages using GitHub Actions. The site includes blog posts and notes with custom ULID-based permalinks.

Development Commands

Local Development

# Install dependencies
bundle install

# Run local development server
bundle exec jekyll serve

# Build the site for production
bundle exec jekyll build

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

Creating Content

# Generate a new note with ULID-based filename
bin/generate-note "Title of your note" -t tag1,tag2

Content Structure

  • Posts: _posts/YYYY-MM-DD-post-title.md - Blog posts using Jekyll’s standard naming convention
  • Notes: _notes/[ULID].md - Short notes with ULID-based permalinks (e.g., /notes/01JFAY4ZQWXYZ123456789ABCD/)
  • Images: assets/images/ - Static images referenced in content
  • Talks: talks/ - Static presentation files (kept via keep_files in _config.yml)

Key Configuration

  • _config.yml: Main Jekyll configuration
    • Theme: minima
    • Base URL: https://random.qmx.me
    • Permalinks:
      • Posts: /posts/:year/:month/:day/:slug/
      • Notes: Set by ULID plugin based on filename
    • Plugins: jekyll-feed, jekyll-sitemap, jekyll-seo-tag, jekyll-paginate, jekyll-redirect-from
    • Collections: notes (with custom ULID-based permalinks)
    • Layouts: default, home, post, note, tag

Custom Plugins Architecture

_plugins/ulid_notes.rb

  • Hooks into Jekyll’s :notes collection at :pre_render phase
  • Validates filenames match ULID pattern (26 uppercase alphanumeric chars)
  • Automatically sets permalink to /notes/{ULID}/
  • Extracts date from ULID timestamp if not set in front matter
  • Uses the ulid gem for ULID parsing

_plugins/tag_page_generator.rb

  • Generator that runs during Jekyll build
  • Collects all unique tags from both posts and notes collections
  • Creates individual tag pages at /tags/{tag}/ using the tag.html layout
  • Tag names are normalized (lowercase, spaces/dots replaced with hyphens)

bin/generate-note

  • Ruby script for creating new notes with proper ULID filenames
  • Generates ULID using ULID.generate
  • Creates file at _notes/{ULID}.md with front matter template
  • Accepts title as argument and optional tags via -t flag

GitHub Actions Deployment

The site uses GitHub Actions workflow (.github/workflows/jekyll.yml) with:

  • Ruby 3.2 (required for activesupport dependency from jemoji)
  • Automatic build and deployment to GitHub Pages on push to main/master branches
  • Pull request builds (but no deployment)
  • Concurrent builds are cancelled for new pushes

Dependencies Note

The jemoji gem (GitHub emoji support) pulls in activesupport which requires Ruby >= 3.2.0