CLAUDE.md

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

Overview

Personal technical blog at https://pibieta.github.io, built with Quarto. Posts are .qmd files that mix Markdown, LaTeX math, and executable Python chunks. Rendered HTML is pushed to the gh-pages branch via GitHub Actions on every push to main.

Commands

# Activate the Python environment (required before quarto commands that execute code)
source .venv/bin/activate

# Live-reload preview at http://localhost:4848
quarto preview

# Full render to _site/
quarto render

# Render a single post only
quarto render posts/my-post/index.qmd

New Python packages used in posts must be added to requirements.txt and committed — the CI workflow installs only from that file.

Writing a new post

mkdir -p posts/my-new-post
# Create posts/my-new-post/index.qmd

Required front matter:

---
title: "..."
description: "One-sentence summary shown on the listing page."
date: 2026-05-16
categories: [tag1, tag2]
draft: false
---

Set draft: true to exclude from the listing while working. The posts/_metadata.yml file applies defaults to every post (author block, jupyter: python3, freeze: auto, TOC settings).

Key architectural decisions

Freeze / caching — execute: freeze: auto in _quarto.yml means Python chunks are only re-executed when the source .qmd changes. Frozen outputs live in _freeze/. Commit _freeze/ so CI doesn’t need to re-run expensive computations.

Math — KaTeX is configured globally (html-math-method: katex). If a post needs \begin{align*} or custom \newcommand macros, switch that post to MathJax by adding html-math-method: mathjax to its front matter.

Citations — Global bibliography is references.bib (APA style via apa.csl). Post-specific .bib files can be referenced with bibliography: ../../references.bib (or a local override) in the post’s front matter. Render the bibliography in a post with:

## References {.unnumbered}
::: {#refs}
:::

Themes — Light/dark themes are customized in theme-light.scss / theme-dark.scss. Global CSS overrides go in styles.css.

Callout blocks for theorems, proofs, and asides:

::: {.callout-note title="Theorem" appearance="simple"}
...
:::

Available types: note, tip, warning, caution, important.

Deployment

Pushing to main triggers .github/workflows/publish.yml, which renders the site and force-pushes _site/ to gh-pages. The workflow pins Quarto 1.5.57 and Python 3.11.

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Overview Personal technical blog at <https://pibieta.github.io>, built with [Quarto](https://quarto.org). Posts are `.qmd` files that mix Markdown, LaTeX math, and executable Python chunks. Rendered HTML is pushed to the `gh-pages` branch via GitHub Actions on every push to `main`. ## Commands ```bash # Activate the Python environment (required before quarto commands that execute code) source .venv/bin/activate # Live-reload preview at http://localhost:4848 quarto preview # Full render to _site/ quarto render # Render a single post only quarto render posts/my-post/index.qmd ``` New Python packages used in posts must be added to `requirements.txt` and committed — the CI workflow installs only from that file. ## Writing a new post ```bash mkdir -p posts/my-new-post # Create posts/my-new-post/index.qmd ``` Required front matter: ```yaml --- title: "..." description: "One-sentence summary shown on the listing page." date: 2026-05-16 categories: [tag1, tag2] draft: false --- ``` Set `draft: true` to exclude from the listing while working. The `posts/_metadata.yml` file applies defaults to every post (author block, `jupyter: python3`, `freeze: auto`, TOC settings). ## Key architectural decisions **Freeze / caching** — `execute: freeze: auto` in `_quarto.yml` means Python chunks are only re-executed when the source `.qmd` changes. Frozen outputs live in `_freeze/`. Commit `_freeze/` so CI doesn't need to re-run expensive computations. **Math** — KaTeX is configured globally (`html-math-method: katex`). If a post needs `\begin{align*}` or custom `\newcommand` macros, switch that post to MathJax by adding `html-math-method: mathjax` to its front matter. **Citations** — Global bibliography is `references.bib` (APA style via `apa.csl`). Post-specific `.bib` files can be referenced with `bibliography: ../../references.bib` (or a local override) in the post's front matter. Render the bibliography in a post with: ```markdown ## References {.unnumbered} ::: {#refs} ::: ``` **Themes** — Light/dark themes are customized in `theme-light.scss` / `theme-dark.scss`. Global CSS overrides go in `styles.css`. **Callout blocks** for theorems, proofs, and asides: ```markdown ::: {.callout-note title="Theorem" appearance="simple"} ... ::: ``` Available types: `note`, `tip`, `warning`, `caution`, `important`. ## Deployment Pushing to `main` triggers `.github/workflows/publish.yml`, which renders the site and force-pushes `_site/` to `gh-pages`. The workflow pins Quarto 1.5.57 and Python 3.11.