CLAUDE.md

CLAUDE.md

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

Overview

Jekyll personal/academic site (bagustris.github.io) using the remote theme bagustris/primer2-theme (set in _config.yml). Layouts largely come from the theme; local _layouts/, _includes/, _sass/ override or extend it. _site/ is generated output — never edit it. No automated tests; verify by serving the site and checking pages in a browser.

Commands

# Docker (preferred); serves http://localhost:4000 with watching
docker compose -f docker-compose-28.yaml up      # Docker 28+
docker-compose -f docker-compose.yaml up         # older Docker
make serve | build-site | stop                   # Makefile wrappers (use legacy docker-compose)

# Without Docker
bundle install
bundle exec jekyll serve -H 0.0.0.0 -w --config _config.yml,_config_docker.yml

_config_docker.yml overrides url to "" for local serving. _config.yml is NOT hot-reloaded; restart the server after editing it.

Architecture

  • Content: _pages/ (static pages, each with its own permalink), _posts/ (blog), plus collections _publications, _talks, _teaching, _portfolio (defined in _config.yml). ja/ holds Japanese mirror pages; English/Japanese pairs are linked by matching lang / lang_ref front matter.
  • Navigation: _data/navigation.yml (supports title_ja/url_ja for bilingual items). New top-level pages must be added here to show in the sidebar.
  • Posts: the defaults in _config.yml give posts layout: single, author_profile: true, and permalink /blog/:title/. The blog index is _pages/blog.md (loops site.posts).
  • Layout gotcha: layout: compress minifies HTML, so theme toggle and sidebar behavior live in inline vanilla JS, not the jQuery bundle (see memory note compress-inline-js).
  • Assets: images/<post-topic>/, files/ (downloadable PDFs), fonts/, assets/.
  • Post figures are generated by Python scripts in blogs/ (e.g. blogs/gop_figures.py, blogs/bootstrap_ci_figures.py, run from repo root; matplotlib; write to images/<topic>/NN-name.png). blogs/ also holds an unrelated health-report analysis. Keep the script committed with the PNGs, and link it at the end of the post.

Blog post conventions

File: _posts/YYYY-MM-DD-slug.md. Front matter: title, description, excerpt, date: YYYY-MM-DD 00:00:00 +0900 (no layout; comes from defaults). Embed images as <img src="/images/%3Ctopic%3E/01-name.png" alt="...">.

Style: plain, simple English, short sentences, beginner-friendly, numbered ## sections, tables for symbol glossaries, small worked numeric examples.

Every post follows this structure:

  1. Intro — open with a concrete question or problem the reader cares about, define the key term in bold, and say what the post will give them. No preamble.
  2. Visualization first — show a figure early (before heavy math) that captures the core idea; explain how to read it (axes, colors, panels A/B, what to notice). Label panels and state when data are simulated.
  3. Main content — build the idea step by step in numbered sections, each tied to a figure or example; one new concept per section.
  4. Annotation — annotate every equation, image, and code block: a figure of the equation with each symbol labeled, plus a plain-text version and a symbol/meaning table; explain how to interpret the result (range, sign, “close to X means…”). Add a worked numeric example. Give every image meaningful alt text.
  5. Conclusion — a “Limits to keep in mind” section (caveats) if relevant, then a short Summary restating the idea in one or two sentences, followed by references (italic) and the link to the figure script.