CLAUDE.md

1# PHPStan Website (phpstan.org)
2 
3Static website for PHPStan - PHP Static Analysis Tool.
4 
5## Tech Stack
6 
7- **Static site generator:** Eleventy (11ty) v2
8- **Bundler:** Vite
9- **Styling:** TailwindCSS v3 with PostCSS and autoprefixer
10- **Templating:** Nunjucks (11ty layouts/includes), Markdown (content pages, blog posts)
11- **Client-side JS:** TKO (Technical Knockout 4, the Knockout.js successor), TypeScript (ES6 target), jQuery
12- **Code editor:** CodeMirror 6 (playground)
13- **Syntax highlighting:** Prism.js (build-time via 11ty plugin)
14- **Search:** Algolia DocSearch
15- **Markdown:** markdown-it with plugins (anchors, footnotes, abbreviations, attrs)
16 
17## Build Pipeline
18 
19The build is a two-stage process:
20 
211. **`npm run build:11ty`** — Eleventy compiles templates and content from `src/` into `tmp/`
222. **`npm run build:vite`** — Vite bundles and optimizes everything from `tmp/` into `dist/`
23 
24The final deployable output is the `dist/` directory.
25 
26### Key Directories
27 
28- `src/` — Source files (templates, content, styles, TypeScript)
29- `tmp/` — Intermediate build output from Eleventy (gitignored)
30- `dist/` — Final build output from Vite (gitignored)
31 
32### Scripts
33 
34- `npm run build` — Full production build (11ty + Vite)
35- `npm run watch` — Dev mode (runs 11ty watch + Vite dev server in parallel)
36- `npm run check` — TypeScript type-check + ESLint
37- `npm run fix` — ESLint auto-fix
38- `npm run test:visual` — Run Playwright visual regression tests
39- `npm run test:visual:update` — Update visual test snapshots
40 
41### Deployment
42 
43Built on GitHub Actions, deployed to AWS S3 (`web-phpstan.org` bucket) with CloudFront CDN invalidation. Triggered by pushes to `2.1.x` branch affecting `website/**`.
44 
45## Source Structure
46 
47- `src/_layouts/` — Nunjucks page layouts
48- `src/_includes/` — Nunjucks partial templates
49- `src/_data/` — 11ty global data files
50- `src/_posts/` — Blog posts (Markdown)
51- `src/js/` — TypeScript source files
52- `src/user-guide/` — User guide documentation (Markdown)
53- `src/developing-extensions/` — Extension development docs
54- `src/writing-php-code/` — PHP writing guide
55- `src/app.pcss` — Main stylesheet (Tailwind + custom CSS)
56- `visual-tests/` — Playwright visual regression tests and baseline screenshots
57 
58## Eleventy Configuration
59 
60Configured in `.eleventy.js`:
61- Input: `src/`, Output: `tmp/`, Layouts dir: `_layouts`
62- Plugins: syntax highlighting (with diff support), RSS, rendering
63- Custom filters for dates (Luxon), reading time, path trimming
64- Mermaid diagram rendering with file-based caching
65- Social image generation via `capture-website`
66 
67## Verifying Changes
68 
69Run `npm run test:visual` to execute Playwright visual regression tests. These tests compare screenshots against baseline snapshots stored in `visual-tests/`. If changes are intentional, update snapshots with `npm run test:visual:update`.
70 
71When making changes, build with `npm run build` and compare the `dist/` directory before and after. Some differences are expected (hashed filenames, minor whitespace) but:
72- No whole sections of generated HTML should disappear
73- The website should still look the same visually
74- Check that pages render correctly, not just that the build succeeds
75 
76### Playwright Screenshots for UI Development
77 
78When working on visual UI changes (especially the playground), use Playwright to take screenshots and iterate on the design. The dev server runs at `http://localhost:5173` (started via `npm run watch`). Use Node.js scripts with `@playwright/test` (installed in the project) like this:
79 
80```js
81node -e "
82const { chromium } = require('@playwright/test');
83(async () => {
84  const browser = await chromium.launch();
85  const page = await browser.newPage({ viewport: { width: 1280, height: 900 } });
86  await page.goto('http://localhost:5173/try');
87  await page.waitForTimeout(2000);
88  // Interact with the page (click buttons, open dialogs, etc.)
89  await page.click('button:has-text(\"Options\")');
90  await page.waitForTimeout(500);
91  await page.screenshot({ path: '/tmp/screenshot.png' });
92  await browser.close();
93})();
94"
95```
96 
97Also check the browser console for errors:
98 
99```js
100page.on('console', msg => { if (msg.type() === 'error') console.log(msg.text()); });
101page.on('pageerror', err => console.log(err.message));
102```
103 
104Take screenshots at multiple viewport sizes (desktop 1280x900, mobile 375x812) to verify responsive layouts. Read the screenshot images to visually inspect the result, then adjust code and re-screenshot as needed.
105