CLAUDE.md

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

What This Is

Richard Sprague’s personal website at https://richardsprague.com, built with Quarto. Content covers health/microbiome research, technology, and personal projects. Source .qmd files are rendered to HTML in /docs/, which is committed to git and deployed via rsync to Ionos hosting.

Key Commands

Preview locally (renders and serves with live reload):

quarto preview
# or Cmd+Shift+B in VS Code (configured in .vscode/tasks.json)
# Preview runs at http://localhost:4200

Deploy to production (rsync /docs/ to Ionos):

./publish

Render without preview:

quarto render

Architecture

Content Flow

  1. Write/edit .qmd (Quarto Markdown) source files in topic directories
  2. quarto preview renders to /docs/ and serves locally
  3. ./publish rsyncs /docs/ to Ionos production server
  4. Commit rendered /docs/ along with source .qmd files to git

Directory Structure

Sidebar nav (defined in _quarto.yml): - Basics — about.qmd, topics.qmd, colophon.qmd, plus nested Archive subsection (archive.qmd, post/post.qmd, note/note.qmd) - Health — microbiome/, health/diet/, health/healthtech/ - Technology — tech/, tech/crypto/ - Posts — posts/ - Personal — personal/

Migrated blog archive (from Hugo/blogdown spragueblog): - post/ — blog posts in post/YYYY/MM/DD/slug/index.qmd format (~72 posts) - note/ — microbiome notes and reference material in note/YYYY/MM/DD/slug/index.qmd format (~43 notes) - These contain pre-rendered R plots as PNG images (R code chunks use eval: false since outputs are baked in) - Archive listing pages (post/post.qmd, note/note.qmd) are nested under the Basics > Archive subsection in sidebar

Hub/listing pages: - Each section has an index .qmd (e.g., health/diet/diet.qmd) as its landing page - topics.qmd — aggregated listing across all sections with filter/search UI

Other directories: - /docs/ — all rendered HTML output (committed to git) - /_freeze/ — cached computation results (gitignored) - /_extensions/ — Quarto extensions (currently just iconify)

Configuration

  • _quarto.yml — site config: theme (litera), output dir (docs/), sidebar structure, analytics, preview port (4200)
  • css/normalize.css — custom CSS applied globally
  • schema-org.lua — Lua filter that injects JSON-LD structured data (BlogPosting/Person/WebPage) into every page
  • llms.txt — AI-readable site summary (listed in resources: so Quarto copies it to docs/)
  • execute: freeze: auto means previously-rendered computational content is reused unless source changes
  • Files with R code that lack installed packages should use freeze: true (not auto) to prevent re-execution errors

Deployment

  • Production: Ionos via ./publish (rsync to u73736168@home474626331.1and1-data.host:RichardSprague/)
  • Staging option: ionos git branch is watched by Ionos Deploy Now at https://home-5010302882.app-ionos.space/
  • GitHub Pages (gh-pages branch) exists but is not currently used

Content Notes

  • New posts go in the appropriate section directory as .qmd files
  • Migrated posts from spragueblog live in post/ and note/ with Hugo-style nested date paths
  • After editing .qmd files, always run quarto preview or quarto render before deploying — the /docs/ HTML must be regenerated
  • The freeze: auto setting means computation-heavy documents are cached; force re-render with quarto render --no-cache if needed
  • All content pages should have a description: field in YAML frontmatter for SEO (populates og:description and twitter:description)