Automate documentation screenshot generation with Playwright

[berntpopp]

Summary

Implement automated screenshot generation for the Quarto documentation to keep images in sync with the production/development site and reduce manual maintenance burden.

Current State

• 57 screenshot images (~19MB) in documentation/static/img/
• Manual annotations with numbered callouts, arrows, and labels
• Screenshots become outdated as UI evolves
• Inconsistent styling across different screenshots
• Time-consuming manual process to update

Proposed Solution

Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  Playwright     │ -> │  Post-Process    │ -> │  Final Images   │
│  Raw Screenshots│    │  (Sharp/Canvas)  │    │  with Labels    │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Implementation Options

Approach	Pros	Cons
shot-scraper (Python/CLI)	Purpose-built for docs, YAML config, Simon Willison's tool	Annotations via JS injection
Playwright + Sharp (Node.js)	Full control, native to our stack	More code to maintain
Playwright MCP	AI-assisted, modern	Newer, less documented

Recommended Approach

1. Create screenshot manifest (scripts/doc-screenshots.json)

   • Define each screenshot: URL, selectors, viewport, annotations

2. Playwright capture script (scripts/generate-doc-screenshots.js)

   • Navigate to each page
   • Wait for content/animations
   • Inject CSS highlights for elements
   • Capture raw screenshots

3. Post-processing with Sharp

   • Add numbered circle markers (1, 2, 3...)
   • Add arrows pointing to elements
   • Add text labels
   • Optimize image size (WebP conversion?)

4. GitHub Actions workflow

   • Trigger: manual, weekly schedule, or on UI changes
   • Run against dev or prod site
   • Commit updated images automatically

Screenshot Manifest Example

{
  "screenshots": [
    {
      "id": "02_01-landing-page",
      "url": "/",
      "viewport": { "width": 1920, "height": 1080 },
      "fullPage": false,
      "annotations": [
        { "selector": "nav.navbar", "label": "1) top menu", "arrow": "right" },
        { "selector": "main", "label": "2) content", "arrow": "right" },
        { "selector": "footer", "label": "3) footer", "arrow": "right" }
      ]
    },
    {
      "id": "02_02-navigation-menu-tables",
      "url": "/",
      "actions": [
        { "type": "click", "selector": "[data-toggle='dropdown']:has-text('Tables')" }
      ],
      "waitFor": ".dropdown-menu.show"
    }
  ]
}

Tasks

• Research and finalize tool choice (shot-scraper vs custom Playwright)
• Create screenshot manifest for all 57 images
• Implement capture script with element highlighting
• Implement annotation overlay (numbered markers, arrows, labels)
• Add Sharp post-processing for consistent styling
• Create GitHub Actions workflow
• Test against dev environment
• Document the process for future updates
• Consider WebP conversion for smaller file sizes

References

• shot-scraper by Simon Willison
• Playwright Screenshots API
• Playwright MCP for Documentation
• Kong Docs Screenshot Automation
• marker.js for annotations
• Sharp image processing

Related

• Part of Phase 62: Admin & Infrastructure (documentation migration)