|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Commands |
| 6 | + |
| 7 | +```bash |
| 8 | +npm run dev # Start dev server (http://localhost:5173) |
| 9 | +npm run build # tsc -b && vite build |
| 10 | +npm run lint # ESLint with max-warnings 0 |
| 11 | +npm run preview # Preview production build locally |
| 12 | +``` |
| 13 | + |
| 14 | +There is no test suite. Deploys automatically to GitHub Pages on push to `main` via `.github/workflows/deploy.yml`. |
| 15 | + |
| 16 | +## Architecture |
| 17 | + |
| 18 | +Personal technical blog — React 19 + TypeScript + Vite, client-side only, deployed as static files. |
| 19 | + |
| 20 | +**Routing** (React Router DOM 7): |
| 21 | +- `/` → Home with hero and 3D model viewer |
| 22 | +- `/notes` → Searchable, tag-filtered post listing |
| 23 | +- `/notes/:slug` → Individual post (MDX + TOC + comments) |
| 24 | + |
| 25 | +**Content model** — posts are defined in two places: |
| 26 | +1. **Metadata**: `/src/data/notes.ts` — a typed `Note[]` array (slug, title, date, tags, excerpt, category). No YAML frontmatter. |
| 27 | +2. **Content**: `/src/content/notes/{slug}.mdx` — MDX files discovered and lazy-loaded at runtime via `import.meta.glob('../content/notes/*.mdx')` in `NoteView.tsx`. |
| 28 | + |
| 29 | +Adding a new post requires entries in both files. |
| 30 | + |
| 31 | +**MDX pipeline** (configured in `vite.config.ts`): |
| 32 | +- `remark-gfm` + `remark-math` → parse GFM and `$$...$$` LaTeX |
| 33 | +- `rehype-highlight` → code syntax highlighting |
| 34 | +- `rehype-katex` → render math |
| 35 | +- Components are injected via `MDXProvider` in `NoteView.tsx`, mapping HTML elements to MUI Typography variants |
| 36 | + |
| 37 | +**Key libraries:** |
| 38 | +- Three.js + React Three Fiber — 3D model rendering in `ModelViewer.tsx` |
| 39 | +- `react-py` — Python WASM interpreter powering `PythonREPL.tsx` |
| 40 | +- Material-UI 7 with Emotion — all styling; light/dark theme in `/src/theme/` |
| 41 | +- KaTeX — math rendering |
| 42 | +- Giscus — GitHub-backed comments (`GiscusComments.tsx`) |
| 43 | + |
| 44 | +**Theme**: Light/dark toggle persisted in `localStorage`. MUI theme and a React context (`ThemeContext`) are set up in `/src/theme/`. The `ModelViewer` adapts its environment map based on the active theme. |
| 45 | + |
| 46 | +**Interactive components** (embeddable in MDX): `PythonREPL`, `ModelViewer`, `AnatomyAttention` (loads external CDN libs dynamically and uses imperative DOM refs alongside React). |
| 47 | + |
| 48 | +## Conventions |
| 49 | + |
| 50 | +- ESLint flat config (`eslint.config.js`); `react/no-unknown-property` is disabled globally to allow Three.js JSX props. |
| 51 | +- `tsconfig.json` uses project references: `tsconfig.app.json` for `/src`, `tsconfig.node.json` for Vite config. |
| 52 | +- Static assets (`.glb` models, images) live in `/public/`. |
0 commit comments