Documentation Screenshots

This directory contains screenshots for the BugPin documentation.

Images are automatically optimized by @docusaurus/plugin-ideal-image which generates responsive sizes and WebP versions.

Image Specifications

Resolution (Dimensions)

Source images should be:

• Desktop screenshots: 1920x1080 (Full HD) - Recommended
• UI components/dialogs: 1280x800 to 1920x1080
• Small UI elements: Actual size (no upscaling)
• Maximum width: 1920px (plugin configured limit)

File Size

Before optimization:

• Target: < 2MB per screenshot
• Ideal: < 1MB per screenshot
• Maximum: < 5MB (compress if larger)

After plugin optimization:

• WebP: ≈ 100-300KB
• PNG fallback: ≈ 200-500KB
• Responsive sizes automatically generated

Format

• ✅ PNG - Use for UI screenshots (best text clarity)
• ⚠️ JPEG - Only for photos (not recommended for UI)
• ❌ WebP - Don't save manually (plugin generates this)

Naming Convention

Use descriptive kebab-case names:

Good examples:

• admin-login-screen.png
• project-create-dialog.png
• widget-button-bottom-right.png
• github-integration-settings.png

Bad examples:

• Screenshot 2024-01-29.png ❌
• image1.png ❌
• IMG_0123.png ❌

Taking Screenshots

Browser Setup

• Viewport size: 1920x1080
• Browser: Clean UI (hide bookmarks bar)
• Theme: Light or dark mode as specified
• Zoom: 100% (no browser zoom)

Tools

• macOS: Cmd+Shift+4 or Cmd+Shift+5
• Windows: Win+Shift+S or Snipping Tool
• Browser DevTools: F12 → Device Toolbar → Set 1920x1080

Best Practices

• Use example data: [email protected], "My Project"
• Hide real email addresses and sensitive information
• Crop to relevant UI area
• Remove unnecessary margins
• Ensure text is readable
• Use consistent styling

Compression (Optional but Recommended)

Pre-compress large files before committing:

Tools:

• TinyPNG - Online, easy to use
• ImageOptim - macOS app
• Squoosh - Google web app

Target: 500KB - 1MB per screenshot

Quick Reference

Screenshot Type	Resolution	Max Size	Format
Full page	1920x1080	< 1MB	PNG
Dialog/Modal	1280x800	< 500KB	PNG
UI component	≤1920px width	< 500KB	PNG
Icon/Button	2x actual (retina)	< 100KB	PNG

Referencing in Documentation

Use relative paths from the markdown file:

![Login Screen](./images/login-screen.png)
_The admin login screen showing default credentials_

The plugin automatically:

• ✅ Generates responsive image sizes (640px, 1920px)
• ✅ Creates WebP versions for modern browsers
• ✅ Adds lazy loading
• ✅ Shows low-quality placeholder while loading
• ✅ Generates srcset for responsive loading

Screenshot Locations

Organize screenshots by documentation section:

• docs/images/ - Intro and Quick Start
• docs/installation/images/ - Installation guides (Docker, Bun, Reverse Proxy)
• docs/configuration/images/ - Configuration (Server, Widget, Branding, Users)
• docs/widget/images/ - Widget installation and annotation tools
• docs/integrations/images/ - GitHub and other integrations

Workflow

1. Take screenshot at 1920x1080 or actual size
2. Crop to relevant area
3. Optionally compress if > 1MB
4. Save as PNG with descriptive kebab-case name
5. Add to appropriate docs/*/images/ folder
6. Reference in markdown: ![Alt](./images/name.png)
7. Plugin handles optimization automatically

Examples

✅ Good Screenshot

File: login-screen.png
Resolution: 1920x1080
Size: 450KB
Contains: Admin login with example credentials
Result: 120KB WebP + 280KB PNG fallback

❌ Too Large

File: dashboard.png
Resolution: 3840x2160 (4K)
Size: 8MB
Problem: Wastes bandwidth, slow builds
Solution: Resize to 1920x1080 first

❌ Too Small

File: button.png
Resolution: 400x200
Size: 20KB
Problem: Pixelated on retina displays
Solution: Use 800x400 or actual retina size

---

Plugin Configuration: See docusaurus.config.ts for optimization settings (quality: 85, max: 1920, steps: 2)