1 CLAUDE.md — steveya.github.io

1.1 Project overview

This is a Quarto-based static website deployed to GitHub Pages. It serves as a personal research blog focused on quantitative finance, data science, and machine learning. Content is organized as multi-part series and standalone notes.

1.2 Repository structure

├── _quarto.yml              # Main Quarto config (theme, navbar, format)
├── index.qmd                # Homepage
├── styles.css               # Global CSS
├── references.bib           # Shared bibliography (BibTeX)
├── posts/                   # Published posts (each in posts/<slug>/index.qmd)
│   └── _metadata.yml        # Shared post metadata (bibliography path)
├── pages/                   # Navigation pages (series, notes, projects, categories, about, search)
├── scripts/                 # Python build utilities
│   ├── generate_indexes.py  # Pre-render: generates pages/ from post metadata
│   ├── new_post_from_notebook.py  # Creates draft notebooks
│   └── preview_notebook_post.sh   # Previews notebook as rendered post
├── blog_styles/             # Python plotting/table style library
├── data/                    # YAML data files (projects.yml)
├── assets/                  # Static images and media
├── _includes/               # HTML templates (nav.html)
├── drafts/                  # Private notebook drafts (ignored by Quarto)
├── tests/e2e/               # Playwright smoke tests
├── docs/                    # Rendered output (committed for GitHub Pages)
└── .github/workflows/       # CI and deploy pipelines

1.3 Common commands

# Full site render (also runs generate_indexes.py as pre-render step)
quarto render

# Render a single post
quarto render posts/<slug>/index.qmd

# Render a single page
quarto render pages/<name>.qmd

# Live preview with hot reload
quarto preview

# Run E2E smoke tests (requires Playwright installed)
npm test

# Serve rendered docs locally
npm run serve:docs

1.4 Build and test

Build: npm run build (alias for quarto render). The pre-render hook automatically runs python3 scripts/generate_indexes.py to regenerate index pages from post metadata.

Test: npm test runs Playwright E2E tests against the rendered docs/ directory. Tests cover search filtering and bibliography rendering.

CI: On every PR and push to main, GitHub Actions (.github/workflows/ci.yml): 1. Renders the site with quarto render and fails on any WARN-level messages 2. Runs Playwright smoke tests

Always ensure quarto render produces zero warnings before pushing.

1.5 Creating new posts

1.5.1 Post structure

Each post lives in posts/<slug>/index.qmd with YAML frontmatter:

---
title: "Post Title"
date: YYYY-MM-DD
description: "One sentence summary"
categories: [Category1, Category2]
content-type: "series"    # or "note"
series-id: "series-slug"  # if series
series-title: "Series Name"
series-part: 1
project-ids: [project-id] # optional
---

1.5.2 Stealth notebook workflow

Draft privately, publish when ready:

# Create a draft notebook
python scripts/new_post_from_notebook.py --slug <slug> --title "<Title>" \
  --categories "Cat1, Cat2" --description "One sentence"

# Preview as rendered post
scripts/preview_notebook_post.sh drafts/<slug>.ipynb <slug>

# Publish: keep posts/<slug>/index.qmd, leave notebook in drafts/

Draft files are excluded via .quartoignore: drafts/, posts/**/draft.ipynb, posts/**/_draft.ipynb.

1.5.3 Index generation

scripts/generate_indexes.py scans all posts/*/index.qmd files and auto-generates: - pages/series.qmd — posts grouped by series - pages/notes.qmd — standalone notes - pages/projects.qmd — from data/projects.yml - pages/categories.qmd — category listings

This runs automatically as a Quarto pre-render hook. Do not edit generated pages manually.

1.6 Citations

1.7 Styling

1.8 Writing and prose requirements

These rules apply to all post content. Follow them strictly.

1.9 Key conventions