CLAUDE.md - Jekyll Blog: “Han, Not Solo”

Personal blog by Han Lee on machine learning engineering, compound AI systems, search/information retrieval, and recsys. Hosted on GitHub Pages at https://leehanchung.github.io.

Build & Development Commands

# Install dependencies
gem install bundler && bundle install

# Build the site
bundle exec jekyll build

# Serve locally with live reload
bundle exec jekyll serve --livereload

# Validate HTML output (run after build)
bundle exec htmlproofer ./_site --ignore-status-codes "999,429,403" --ignore-urls "/twitter.com/,/x.com/"

Important: After any content or template change, always run bundle exec jekyll build to verify the site builds without errors.

Project Architecture

├── _config.yml              # Jekyll site configuration (rarely changed)
├── _layouts/                # Page templates: default, home, post, page, portfolio
├── _includes/               # Reusable HTML partials (head, header, footer, analytics, etc.)
├── _sass/minima/            # Theme styles (Minima 2.x)
├── _data/                   # Data files: SocialNetworks.yml, ui-text.yml
├── assets/
│   ├── css/                 # Custom stylesheets
│   ├── fonts/               # Custom fonts
│   └── img/YYYY-MM-DD/      # Post images organized by date
├── blogs/_posts/            # Blog posts (primary content, ~83 posts)
├── notebooks/_posts/        # Tutorial/notebook posts
├── projects/_posts/         # Project writeups
├── talks/_posts/            # Talk/presentation posts
├── about/                   # About page
├── scripts/                 # Utility scripts (image optimization)
└── .github/workflows/       # CI/CD

Content Conventions

Creating a New Blog Post

1. Create file: blogs/_posts/YYYY-MM-DD-slug-title.md
2. Create image directory (if needed): assets/img/YYYY-MM-DD/
3. Add frontmatter (see template below)
4. Write content in Kramdown/GFM markdown

Frontmatter Template

Every post MUST have this frontmatter structure:

---
layout: post
type: post
title: "Post Title Here"
subtitle: "Optional subtitle"
thumbnail: "/assets/img/YYYY-MM-DD/thumbnail.png"  # optional
date: YYYY-MM-DD
author: "Han Lee"
category: blogs          # one of: blogs, notebooks, projects, talks
math: false              # set true if post uses LaTeX
comments: true
published: true          # set false for drafts
tags: [Tag1, Tag2, Tag3]
description: |
  Brief description for SEO and social sharing.
excerpt: |
  Short excerpt shown in post listings.
---

Required fields: layout, type, title, date, author, category, tags
Category values: blogs, notebooks, projects, talks (must match the subdirectory)

Content Guidelines

• Markdown: Kramdown with GFM input. Hard wrap is enabled.
• Code blocks: Use triple backticks with language spec (python,bash, etc.)
• Math: Display mode $$...$$, inline $...$ (set math: true in frontmatter)
• Images: Reference as /assets/img/YYYY-MM-DD/filename.png. Use descriptive filenames.
• Links: Relative paths for internal links, full URLs for external
• Posts with __ prefix: Draft/incomplete posts (e.g., __2021-09-30-ctr-model.md). Do not publish these.

Common Tags

Data Science, DevOps, Evaluation, Generative AI, LLM, Machine Learning, MLOps, NLP, Prompt Engineering, AI Engineering, Compound AI Systems, Agent Systems, Claude Code, Recsys

Tech Stack

• Jekyll 3.8.7 with Minima 2.x theme
• Kramdown markdown processor with GFM input
• Rouge for syntax highlighting
• Plugins: jekyll-feed, jekyll-sitemap, jemoji, jekyll-seo-tag
• Analytics: Google Analytics (UA-142121126-2)
• Comments: Disqus (calabazascreek)
• Ruby: 3.1.x recommended (Jekyll 3.8.7 has compatibility issues with Ruby 3.3+)

Repository Workflow

• Create a branch for changes, then PR to master
• Do not commit directly to the master branch
• Run bundle exec jekyll build to verify changes before committing
• CI will build the site and run HTML validation on PRs

Key Files to Know

Troubleshooting

• Build fails: Check frontmatter YAML syntax (colons in titles must be quoted)
• _config.yml changes not reflected: Restart jekyll serve (config is not live-reloaded)
• Missing images: Verify path matches /assets/img/YYYY-MM-DD/ convention
• Math not rendering: Ensure math: true is set in post frontmatter