Claude Code Instructions for bbum.github.io

Claude Code Instructions for bbum.github.io

Commit Messages

Keep commit messages simple - just bullet points of what changed:

- Added new post about topic
- Fixed typo in about page
- Updated stylesheet

No “Generated by Claude” footers, no co-author lines, no emoji, no fluff.

Dates

ALWAYS check the current date before creating posts. Do NOT assume the year is 2024. Use:

date +%Y-%m-%d

Prefer mdfind over find or grep for file discovery:

mdfind -onlyin . 'kMDItemFSName == "*.md"'
mdfind -onlyin . 'kMDItemTextContent == "*search term*"'

Site Structure

_layouts/            # default.html, post.html, tag.html
_includes/           # header.html, footer.html, amazon.html, vimeo.html
_posts/              # YYYY-MM-DD-title.md
_data/comments/      # comment_id.yml files
_data/timelapses.yml # Video list rendered on /timelapse/ (newest first)
assets/css/          # style.scss
assets/images/amazon/ # Self-hosted Amazon product shots for affiliate cards
tags/                # Individual tag pages (tags/photography/index.html)
toc/                 # Table of contents page
pages/               # Standalone pages (layout: page); listed manually in pages.md

Jekyll (ALWAYS use Makefile)

NEVER run Jekyll commands directly. Use the Makefile:

make serve    # Start dev server with --watch and --livereload
make build    # One-time build
make stop     # Kill running Jekyll server

Before previewing, ensure Jekyll is running with make serve. If preview isn’t updating, check that Jekyll is running with watch mode (the Makefile handles this).

Posts

Photo Workflow (Flickr + Photos Integration)

When adding photos from the Photos library to blog posts:

1. Find and Export from Photos

mcp__conduit__photos action=search_text query="photo name"
mcp__conduit__photos action=export id=PHOTO_ID outputPath=/tmp/photo.jpg format=jpeg quality=high

Export automatically normalizes EXIF orientation (bakes rotation into pixels).

2. Upload to Flickr

mcp__bbflickr__flickr action=upload filePath=/tmp/photo.jpg title="Title" tags="blog" visibility=public

Only use blog tag. NO descriptive tags (3d-printing, TPU, etc.) on either Flickr or Photos.

mcp__bbflickr__bridge action=link flickrID=FLICKR_ID photosID=PHOTOS_ID
mcp__conduit__photos action=set_keywords id=PHOTOS_ID keywords="flickr:FLICKR_ID, blog" append=true

Bridge writes machine tag to Flickr. You must ALSO add flickr:FLICKR_ID keyword to Photos. Photos keywords should ONLY be: flickr:ID and blog (if for blog). NO descriptive tags.

4. Get embed info from Flickr

mcp__bbflickr__flickr action=agent id=FLICKR_ID

Returns YAML with title, flickr_url, tags, and sizes array.

5. Embed in Post (DO NOT use Flickr JS embed)

Use the figure class template, NOT <a data-flickr-embed>:

<div class="figure right">
<img src="https://live.staticflickr.com/65535/PHOTO_ID_SECRET_n.jpg" width="200" height="267" alt="Alt text">
<div class="caption"><a href="https://www.flickr.com/photos/bbum/PHOTO_ID/">Caption</a></div>
</div>

Photo Tagging Requirements

Video Workflow (Vimeo + Photos Integration)

Videos are hosted on Vimeo (paid account; Flickr caps video at 1080p so it is stills-only). Timelapse videos in Photos are identified by original filename “ATLI” and keyword ATLI; the user titles them in Photos.

1. Export original from Photos

mcp__conduit__photos action=export id=PHOTOS_ID outputPath=/tmp/name.mp4 format=original

2. Upload to Vimeo

mcp__bbflickr__vimeo action=upload filePath=/tmp/name.mp4 title="Title" tags="blog" visibility=public

The video is NOT embeddable until transcoding completes — poll with action=show until transcodeStatus is complete.

mcp__bbflickr__bridge action=link vimeoID=VIDEO_ID photosID=PHOTOS_ID
mcp__conduit__photos action=set_keywords id=PHOTOS_ID keywords="vimeo:VIDEO_ID, blog" append=true

4. Embed

<div class="figure video">
<div class="video-frame">
<iframe src="https://player.vimeo.com/video/VIDEO_ID?badge=0&autopause=0" allow="autoplay; fullscreen; picture-in-picture" referrerpolicy="strict-origin-when-cross-origin" title="Title" loading="lazy"></iframe>
</div>
<div class="caption">Title</div>
</div>

Responsive 16:9 player (optional aspect="4 / 3" param). Captions deliberately do NOT link to vimeo.com — keep readers on the blog. Never use Vimeo’s raw iframe embed code directly.

5. Update the /timelapse/ page

For timelapse videos, also append an entry to _data/timelapses.yml (newest first):

- vimeo_id: "VIDEO_ID"
  title: "Title"
  date: YYYY-MM-DD   # capture date

The page itself (pages/timelapse.md) renders the list automatically.

Amazon Affiliate Cards

Amazon no longer generates image+tagline embeds, so the site has its own. For product reviews:

  1. User supplies the product image and an https://amzn.to/... affiliate short link (always use the affiliate link, never a bare amazon.com URL).
  2. Save the image to assets/images/amazon/product-name.jpg.
  3. Embed the card: ```
Alt text
Product Name
View on Amazon →
 
`class` is right/left/center (same float behavior as `.figure`). Scale
height from the image's aspect ratio at the chosen width. The whole card
is one click target with `rel="sponsored"`.

### Post Front Matter

```yaml
---
layout: post
title: "Post Title"
date: YYYY-MM-DD
tags: [tag1, tag2]
comment_id: xYz123
---

Tags

When adding a new tag:

  1. Create tags/newtagname/index.html: 
    ---
layout: tag
tag: newtagname
title: "newtagname"
---

Comments (Email-based)

Comments are collected via email to blog@bbum.net.

Subject Line Format

Processing Comments

When user says to process comments from _incoming_comments/:

  1. Parse each .eml file:
    • Extract IDs from Subject: line: [postID] or [postID:parentCommentID]
    • Extract sender name (not email) from From:
    • Extract date from Date: header
    • Extract body (plain text preferred)

  2. Generate a new 4-char comment ID for this comment

  3. Add to _data/comments/POST_ID.yml: ```yaml
    • id: a3Bx from: “Sender Name” date: 2025-12-22 body: | Comment text here.
  1. Delete processed .eml files
  2. Rebuild site

Comment Data Fields

Comment Data Location

When asked to add a link to the site (e.g., to Laser Resources), visit the URL first to determine:

Don’t ask the user for this info if it can be determined from the site itself.

Constraints