CLAUDE.md

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

What this repo is

Personal website/blog published at https://rtviii.xyz, built with Quarto. The CNAME file ties the GitHub Pages deployment to the custom domain. package-lock.json is intentionally empty — there is no Node/JS toolchain; Quarto is the only build tool.

Commands

  • quarto preview — local dev server with live reload
  • quarto render — full build of the site into _site/
  • quarto render posts/<slug>/index.qmd — render a single post

Architecture

Authoring format is .qmd (Quarto markdown). Site structure:

  • _quarto.yml — single source of site config (theme litera, output dir _site/, header includes). draft-mode: unlinked means draft pages render but aren’t linked from listings.
  • index.qmd — homepage. blog.qmd — auto-listing of posts/ (sorted by date desc). listings.qmd + listings/ — curated reading lists. papers/ — CV and papers page.
  • posts/<slug>/ — published blog posts. Each is a directory with index.qmd, a data/ subdir for figures/assets, and optional per-post references.bib. These are what blog.qmd auto-lists.
  • _wip/ — drafts. The _-prefix means Quarto skips it during render, so drafts stay in the repo but never ship to _site/. Move a directory from here into posts/ to publish it.
  • Long posts may be split across files: posts/<slug>/index.qmd carries the frontmatter and uses {{< include _sections/NN-name.qmd >}} to pull in section files from a _sections/ subdir (underscore prefix prevents Quarto from rendering them as standalone pages). See posts/mmcif/ for the pattern.
  • _includes/ — shared layout partials (_navigation.qmd, _listing_layout.qmd) referenced from frontmatter.
  • _templates/default.html — custom HTML template.
  • molstar_assets/index.js — Mol* 3D structure viewer bundle used by some structural-biology posts.
  • refs.bib — top-level bibliography; individual posts use their own references.bib via bibliography: in YAML frontmatter.
  • _freeze/ — Quarto’s frozen computation cache. Generated; do not hand-edit.
  • _site/ — build output. Generated; do not hand-edit.

Conventions

  • To publish a new post: create posts/<slug>/index.qmd with YAML frontmatter including title, date, categories, and (if cited) bibliography: references.bib. Use _wip/<slug>/ while drafting. For WIP posts inside posts/ (e.g. published slug but not ready), add draft: true to the frontmatter.
  • Do not introduce a Node toolchain — the empty package-lock.json is deliberate.

Blog authoring conventions (Duino / structural-bio series)

Conventions agreed with Artem for the Duino series, and the default for new posts. (The two short rules in .claude/CLAUDE.md — no last-name citations, math symbol dropdowns — are the seed of this and are expanded below.)

Structure: two tiers

The material splits into a Core and a Secondary tier. The Core is the foremost citizen; Secondary chapters matter to the mission but are secondary to the Core in their capacity to address the heterogeneity problem. Core prose may link out to Secondary chapters to call out problems, motivate choices, or elaborate — but Secondary material never pollutes the Core text.

  • Core — the Duino fundamentals, as two tracks: Track A (ensemble representation: Hierarchy, Groupings, Heterogeneity with the three regimes R1/R2/R3, Materialization with the three modes A/B/C) and Track B (forward-operator infrastructure: operator records and the likelihood substrate), plus the evaluation model that composes descriptors into rendered coordinates.
  • Secondary — problems with mmCIF, annotations / the artifact engine, the technology survey, ML-native access patterns, and the appendices.

Chapter 0 splits: the forward-operator material becomes the Track B Core chapter; the statistical-mechanics / Bayesian background becomes a linked prerequisite Primer page (not inlined into the Core).

The series stays a multi-page Quarto website (no book conversion). Global continuous figure numbering across pages is not a priority; per-page cross-references are enough.

Figures

Use Quarto cross-references, never hand-typed “Figure N”. Each figure block carries %| label: fig-<slug> and is referenced with @fig-<slug>, so numbers and links stay correct automatically (per-page numbering is fine; we are not converting to a Quarto book for global numbering).

The Duino concept map (posts/mmcif/concept-map.qmd) is the orientation figure: it goes on the series overview page and is reachable as a hover/tooltip from every chapter.

Every figure carries %| fig-alt: and a %| fig-cap: of the form “Title. one or two sentences.”

TikZ figures share posts/mmcif/data/_tikz-preamble.tex. The palette is semantic and fixed; every new figure reuses it: grey (H0–H4) = hierarchy, teal (accG) = groupings, orange (accS) = discrete states / Regime 1, olive (accT) = trajectory / Regime 2, violet (accO) = operators / Mode C. Reusable styles live in the preamble; figure-specific styles sit atop the block and migrate into the preamble once stable, so the visual language stays continuous.

Citations

Papers always go in references.bib, cited [@key] (numeric superscript). Never cite a paper by last name (no “the Wankowicz-Bonomi line”, no “gemmi (Wojdyr)”) — always link to the bibliography. Software/tools mentioned more than once also get a bib entry (@misc/@software) for a consistent link; a genuine one-off link to a tool’s docs/repo may stay a plain inline link.

Mathematics

Every non-trivial formula is presented the same way: the inline/display math as usual, plus a subtle, unstyled, collapsed-by-default dropdown directly beneath it spelling out each symbol and index. Keep operational symbol-prose out of the running text (it lives in the dropdown) but keep the mathematics lucid. Exempt the elementary cases (definition of covariance, a simple integral, etc.).

Definitions and the glossary

No .def insets in the prose. Canonical concept definitions live in the Glossary (posts/glossary/), organised thematically. The first use of a term in a post is bolded and links to its glossary anchor. The glossary is a first-class part of the series — the single place concepts are defined.

Glossary entries carry explicit {#gloss-<slug>} anchors (e.g. []{#gloss-scope}**Scope.** ...); link first use as [**Term**](../glossary/index.qmd#gloss-<slug>). The chapter nav (_glossary.qmd) links to the glossary so it is always reachable.

Main prose vs. side content (the meat / context split)

The main column carries only load-bearing content: the claims and definitions that actually constitute the format. It is condensed and informative — never vague rambling, and never the residue of an exploratory session (tangents, clarifying back-and-forth, restated context).

Secondary material — elaboration, examples, motivating asides, extra context — does not sit in the main column. It goes into a sidenote: an in-flow Tufte-style margin note that is ALWAYS visible and scrolls with the body text like any other block — never pinned, never collapsed behind a marker, never a popover. Keep this distinct from links and their hover previews, which are a separate mechanism (the Gwern-style link-preview tooltips stay). The .def-stack right-rail machinery is kept but unused in this series; .fold remains for inline collapsibles. Do not remove the right-rail infrastructure. Apply this split when drafting new posts and when reorganising existing ones.

Sidenote syntax: place ::: {.sidenote} ... ::: immediately after the paragraph it elaborates. Placement is pure CSS: on wide viewports (>= 1500px, where the outer gap holds a column) the note floats into the right gap and consecutive notes stack via clear: right so hefty notes push each other down rather than overlap; on narrower viewports it falls back to an in-flow indented block in the reading column. Either way it is always shown and scrolls normally. A small + cue is dropped at the anchor to tie note to sentence; it is a +, not a number, so it never reads as a numeric-superscript citation. To place the cue on a specific phrase instead of the paragraph end, wrap that phrase as [phrase]{.sn-anchor}. The marker injection lives in installSidenotes() (scripts.js); all placement is in the .sidenote* rules in styles/custom.css. Canonical definitions go to the glossary, not a sidenote; sidenotes are for elaboration, examples, and motivating asides.

Voice

Blog-style first person is welcome, but disciplined: keep the voice, drop the solipsistic rambling. Opinion and motivation worth keeping go into a sidenote, not the load-bearing prose.

Naming

The format is “Duino”. Introduce the name once, then use it consistently (not “the new format”).