[Sync to prerelease] Add manifest-driven screenshot capture tooling#1976
Merged
Conversation
Add developer tooling for capturing and maintaining documentation screenshots on quarto.org using Playwright. Screenshots are defined declaratively in a JSON manifest, then captured automatically — no manual screenshotting needed. The tooling lives under _tools/screenshots/ and includes: - capture.js: Playwright-based replay engine that renders pages, executes interactions (clicks, hovers, toggles), and captures screenshots with automatic light/dark variants - manifest.json: Declarative definitions for 17 screenshots (34 images with dark variants) covering about pages, navbar configs, sidebar layouts, breadcrumbs, reader mode, and repo action links - JSON Schema validation for manifest entries - Content-aware trim, crop, and clip-union post-processing via sharp - Spotlight effect for highlighting specific elements - Quarto profile support for rendering different configurations - Example projects under examples/ as minimal screenshot sources (includes quarto-demo as a git subtree) - CI compression workflow (.github/workflows/optimize-images.yml) for oxipng optimization after merge - /screenshot Claude Code skill for interactive screenshot authoring Developed alongside PR #1815 (Twitter → Bluesky migration), which served as real-world validation — all 19 screenshots in that PR were produced by this tool. (cherry picked from commit b184c08)
Member
|
/deploy-preview |
Contributor
Author
📝 Preview Deployment🔍 Full site preview: https://deploy-preview-1976.quarto.org 🔄 Modified Documents🖼️ Pages with Updated Screenshots |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Sync of #1975 to
prerelease.Original PR
Add manifest-driven screenshot capture tooling
What is this?
A developer tool for capturing and maintaining the documentation screenshots on quarto.org. Screenshots are defined declaratively in a JSON manifest, then captured automatically using Playwright — no manual screenshotting needed.
The problem it solves: quarto-web has ~30 screenshots across docs pages (about pages, navigation, sidebars, etc.). When the site design changes or examples need updating, recapturing them manually is tedious and error-prone. This tool makes it repeatable and consistent.
How it works
Everything lives under
tools/screenshots/. The workflow:manifest.json— source page, viewport size, interactions (clicks, hovers), crop/clip regions, dark mode variantnpm run capture— Playwright renders the page, executes the interactions, takes the screenshot, post-processes it (trim, crop, compress)The manifest currently defines 17 screenshots (34 images with dark variants), covering about pages, navbar configurations, sidebar layouts, breadcrumbs, reader mode, and repo action links.
Key capabilities
npm run validate) and IDE autocompletion.github/workflows/optimize-images.yml) — runs oxipng on changed PNGs after mergeExample projects
Small Quarto projects under
examples/serve as screenshot sources. Each is minimal — just enough YAML and content to demonstrate a feature.examples/quarto-demo/is a git subtree of quarto-dev/quarto-demo used for sidebar and navigation screenshots.Live use case: PR #1815
This tooling was developed alongside #1815 (Twitter → Bluesky migration), which needed 19 documentation screenshots recaptured with updated social links. That PR served as the real-world validation — every screenshot in #1815 was produced by this tool and cherry-picked from this branch.
For contributors
Setup requires Node.js and Playwright. From
tools/screenshots/:Then:
npm run capture— capture all screenshotsnpm run capture -- --name navbar-tools— capture a specific entrynpm run capture -- --dry-run— preview the plannpm run capture -- --list— list manifest entriesnpm run validate— validate manifest against schemaSee
tools/screenshots/SETUP.mdfor the full guide.Claude Code integration
A
/screenshotskill guides Claude through the full workflow: creating example projects, iterating on the visual in headed Playwright, encoding the result into the manifest. This is the intended workflow for adding new screenshots — the skill handles the interactive exploration, the manifest captures the result, andcapture.jsreplays it mechanically.