When a merged pull request changes something in your UI, an AI-drafted article about that change is a claim, not proof. DocsKoala's screenshot feature adds the proof: a real before/after picture of the affected page, captured by a headless browser, sitting right next to the draft when a human reviews it.
It's worth being precise about what this feature is and isn't. It's a reviewer aid, evidence that helps you catch a wrong or hallucinated draft before you approve it, not a way to auto-embed screenshots into your live help articles. This guide covers setup and exactly what to expect.
Direct answer
To set up automatic screenshots, open a project's Settings, find the Screenshots section, turn on Auto-screenshots, and enter your app's base URL. If that environment needs a login to view (a Vercel preview, a Cloudflare Access-protected staging site, or Basic Auth), expand "My site needs a login to view it" and fill in the header name and secret, using the Vercel or Cloudflare presets if either applies. From then on, any merged PR that changes UI-shaped files (components, pages, or common frontend file types) automatically triggers a screenshot capture, and the resulting before/after image pair, along with a New/Unchanged/Changed label, appears on that draft's page in the Review Inbox for whoever approves it.
What this feature actually does (and doesn't)
- Trigger: a merged pull request that touches UI-shaped files,
.tsx,.jsx,.vue,.svelte,.astro,.html,.css,.scss,.less, or paths undercomponents/,pages/,views/, ortemplates/. Backend-only changes don't trigger a capture. - Not manual, not scheduled: there's no button to force a re-screenshot on demand today, and nothing recaptures on a timer. It only ever fires off a real UI-affecting merge.
- Route detection is best-effort: DocsKoala tries to work out which page in your app to capture from the file paths that changed (using the Next.js App Router convention). When it can't confidently resolve a specific route, it falls back to capturing your app's base URL instead.
Setting it up
- Open the project's Settings (owner or admin role required) and find the Screenshots section.
- Turn on Auto-screenshots.
- Enter your app's URL, the homepage or base URL of the environment you want captured (typically your production site, or a stable preview environment).
- If that URL needs a login to view, expand "My site needs a login to view it" and configure the header the capture worker should send.
Capturing a login-protected environment
If the URL you want captured sits behind an auth wall, DocsKoala's capture worker can inject a single header on every request. Three presets fill this in for common setups; pick whichever matches, or fill in a custom header manually.
| Preset | What to use | Where to get it |
|---|---|---|
| Vercel | Protection Bypass for Automation header/value | Vercel project settings → Deployment Protection |
| Cloudflare Access | A Service Auth token | Cloudflare Zero Trust → Access → Service Auth |
| Basic Auth / other | A raw header name and value you provide | Whatever your auth layer expects |
Whichever preset you use, the login field name defaults to Authorization (editable), and the secret/token field is write-only: once set, it's never shown again, only replaced.
Reading the before/after result
- Open the relevant draft in the Review Inbox and check its Screenshots tab for the before/after image pair.
- New: no earlier screenshot existed for this page to compare against, this is the first capture.
- Unchanged: pixel comparison against the previous capture found effectively no visible difference, useful confirmation the change was purely internal or backend.
- Changed (N% of pixels): a real visible difference was detected, worth actually looking at the image before approving the draft that claims to describe it.
What's not configurable yet
- No manual trigger. You can't force an immediate recapture from the dashboard, only a new qualifying PR merge fires one.
- One base URL per project. There's no per-page or per-route configuration beyond the automatic best-effort route detection.
- Fixed viewport. Captures are always taken at a single fixed desktop viewport size, there's no control for mobile or custom viewport sizes today.
- No element/selector scoping. Captures are always full-page, there's no way to screenshot just one component or section.
Troubleshooting
| Symptom | Likely cause |
|---|---|
| No screenshot ever shows up on a draft | Auto-screenshots is off, or the merged PR didn't touch any UI-shaped files |
| Capture fails or times out | The base URL isn't reachable publicly, or a protected environment's login header/token is missing or wrong |
| Screenshot is of the wrong page | Route auto-detection couldn't confidently resolve the changed file to a URL and fell back to your base URL, this is more likely on multi-page PRs or non-standard routing |
| Diff shows "Changed" for something you didn't touch visually | Dynamic page content (timestamps, live data, animations) can register as pixel differences even without a real UI change, use it as a signal to check, not an infallible verdict |
Frequently asked questions
Do screenshots get embedded automatically into the published article?
No. They appear alongside the draft in the Review Inbox as evidence for whoever is reviewing it. Adding a screenshot into the article's actual body content is still a manual editing step if you want one there.
Can I manually trigger a screenshot without waiting for a PR?
Not today. Screenshot capture only fires automatically when a merged PR changes UI-shaped files, there's no manual "recapture now" control in the dashboard.
What counts as a UI-affecting change that triggers a capture?
Changes to component/page/view/template files or common frontend file types (.tsx, .jsx, .vue, .svelte, .astro, .html, .css, .scss, .less). Backend-only or non-frontend changes don't trigger a capture.
Can I screenshot a page that requires login?
Yes, if you configure a login header and secret/token in the project's Screenshot settings (with presets for Vercel and Cloudflare Access, or a custom header for anything else), the capture worker sends that header on every request.
What does "Unchanged" vs "Changed" actually mean?
It's a pixel-level comparison against the previous capture of the same page. Effectively no difference is labeled Unchanged; anything above a small noise threshold is labeled Changed, with the percentage of pixels that differed shown alongside it.
Can I control the viewport size or capture just one element?
Not currently. Captures are full-page at a single fixed desktop viewport, there's no per-element selector scoping or custom viewport option today.
Conclusion
- Screenshots are reviewer evidence, a before/after image pair on the draft page in the Review Inbox, not something auto-embedded into your published articles.
- Setup is two fields in Project Settings: enable Auto-screenshots and set your app's base URL, plus an optional login header for protected environments.
- Capture only fires automatically on a merged PR that changes UI-shaped files, there's no manual trigger, scheduled recapture, viewport control, or selector scoping today.
- New/Unchanged/Changed labels tell you whether there's a real visible difference worth checking before you approve the draft describing it.