Paul

Me hacking away at things.

4 minute read

CLAUDE.md

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

What this is

Paul’s personal blog (PaulXiCao.github.io), a Jekyll site hosted on GitHub Pages. Content is mostly IT-related (C++, Linux), plus a German recipe collection. There is no application code — the “source” is Markdown content plus Jekyll/Liquid configuration.

Local development

The site is built in Docker (image jekyll/jekyll, bundle install from the Gemfile), serving with --incremental --livereload:

sudo docker compose up -d
sudo docker compose logs -f dev
# open http://localhost:4000

Rebuilds happen automatically on file change — except _config.yml, which requires restarting the container. There are no tests, linters, or a build step beyond Jekyll.

Architecture

Theme: mmistakes/minimal-mistakes via remote_theme (skin dark). The theme is not vendored, so layouts (single, home, posts, archive) come from the remote gem. To override theme behavior, add files under _includes/, _layouts/, or assets/ mirroring the theme’s paths.

Content lives under collections/ (collections_dir: collections in _config.yml), not in a top-level _posts/:

  • collections/_posts/ — blog posts, filename YYYY-MM-DD-slug.md, date comes from the filename
  • collections/_DSA/, collections/_operating_system/ — multi-part lesson series; ordered by a lesson: front-matter key (sort-by: lesson) and listed on /collections/
  • collections/_rezepte/ — German recipes

Adding a new collection means adding it to the collections: map in _config.yml with output: true; the /collections/ page (_pages/collections.md) then picks it up automatically by iterating site.collections.

Front matter conventions: title, categories (broad: C++, linux, it basics), tags (fine-grained). Posts in a lesson collection also carry date, lesson, and layout: posts. Site-wide defaults (layout: single, author_profile, read_time, classes: wide) are set in the defaults: block of _config.yml, so ordinary posts only need title/categories/tags. Category and tag archive pages are generated from these values via /categories/ and /tags/.

Standalone pages live in _pages/ (included via include: in _config.yml) and each define their own permalink. _data/navigation.yml drives the top nav — a new page is only reachable if added there.

_includes/head/custom.html is the single injection point for site-wide <head> additions and holds three unrelated things:

  1. MathJax (LaTeX in Markdown works out of the box)
  2. A script that appends an “Open in Coliru” button to every ` cpp ` / `c++ ` code block, POSTing the snippet to coliru and opening the resulting share URL. C++ snippets intended to be runnable should therefore be complete, compilable main.cpp programs (compiled with g++ -std=c++23 -O2 -Wall -pedantic -pthread).
  3. Favicon/manifest links

_includes/*.c / *.cpp / Makefile are example sources for the operating-systems series, embedded into posts rather than being part of the build.

scripts/deleteKeys.py is a one-off front-matter sanitizer (strips all keys except title/date/categories/tags) written for a past migration; it hardcodes _posts/old/ and is not part of any workflow.