Docusaurus Screenshot Automation: Keep Your Developer Docs Current with FreshShots

Jan 15, 2025

Docusaurus creates beautiful developer documentation, but keeping screenshots current is a constant struggle. APIs evolve, UIs change, and code examples update frequently. FreshShots automates Docusaurus screenshot management, ensuring your developer docs stay accurate without manual maintenance.

Why Developer Documentation Screenshot Management is Hard

Developer docs have unique challenges:

Rapid iteration: Features change daily in modern development
Multiple environments: Local, staging, production, and demo environments
API versioning: Different versions need different screenshots
Code examples: Screenshots must match current code samples
Open source coordination: Multiple contributors, inconsistent screenshot quality
Technical accuracy: Outdated screenshots confuse developers and slow adoption

How FreshShots Transforms Docusaurus Documentation

FreshShots provides developer-focused automation:

Environment-specific screenshots: Capture from dev, staging, or production
API documentation visuals: Automatically screenshot API responses
Code example synchronization: Screenshots that match current code
Consistent developer experience: Same quality across all documentation
Version control integration: Screenshots update with code deployments

Complete Docusaurus + FreshShots Setup

Step 1: Prepare Your Application for Screenshots

Tag your application’s key interfaces:

<!-- API Dashboard -->
<div data-freshshots-id="api-dashboard" class="dashboard-container">
  <!-- API key management, usage stats -->
</div>

<!-- Code example output -->
<div data-freshshots-id="api-response-example" class="response-container">
  <!-- Live API response -->
</div>

<!-- Developer console -->
<section data-freshshots-id="dev-console" class="console-interface">
  <!-- Interactive API console -->
</section>

<!-- Authentication flow -->
<form data-freshshots-id="auth-flow" class="auth-container">
  <!-- OAuth or API key authentication -->
</form>

Step 2: Create Developer-Focused Workflows

API Documentation Workflow:

[
  {
    "action": "visit_page",
    "url": "https://api-demo.yourapp.com/dashboard"
  },
  {
    "action": "take_screenshot",
    "selector": "api-dashboard",
    "save_screenshot_to": "api-dashboard-overview.png",
    "viewport_size": { "width": 1200, "height": 800 }
  },
  {
    "action": "visit_page",
    "url": "https://api-demo.yourapp.com/console"
  },
  {
    "action": "type_input",
    "selector": "api-endpoint-input",
    "input_value": "/api/v1/users"
  },
  {
    "action": "click_element",
    "selector": "execute-button"
  },
  {
    "action": "take_screenshot",
    "selector": "api-response-example",
    "save_screenshot_to": "api-response-users.png"
  }
]

Authentication Documentation Workflow:

[
  {
    "action": "visit_page",
    "url": "https://yourapp.com/developer/auth"
  },
  {
    "action": "take_screenshot",
    "selector": "auth-flow",
    "save_screenshot_to": "oauth-setup.png"
  },
  {
    "action": "click_element",
    "selector": "generate-key-button"
  },
  {
    "action": "take_screenshot",
    "selector": "api-key-display",
    "save_screenshot_to": "api-key-generated.png"
  }
]

SDK Example Workflow:

[
  {
    "action": "visit_page",
    "url": "https://sdk-demo.yourapp.com/example"
  },
  {
    "action": "take_screenshot",
    "selector": "code-editor",
    "save_screenshot_to": "sdk-code-example.png"
  },
  {
    "action": "click_element",
    "selector": "run-example-button"
  },
  {
    "action": "take_screenshot",
    "selector": "output-console",
    "save_screenshot_to": "sdk-output-result.png"
  }
]

Step 3: Integrate with Docusaurus

Method 1: Direct Markdown Integration

In your Docusaurus markdown files:

---
id: api-overview
title: API Overview
---

# Getting Started with Our API

## Dashboard Overview

![API Dashboard](https://cdn.freshshots.io/1/api-dashboard-overview.png)

The API dashboard provides an overview of your usage, API keys, and quick access to documentation.

## Making Your First Request

![API Response](https://cdn.freshshots.io/1/api-response-users.png)

Here's what a successful response looks like when calling the `/api/v1/users` endpoint.

Method 2: Custom Docusaurus Components

Create reusable screenshot components:

// src/components/FreshShot.jsx
import React from 'react';

export default function FreshShot({ 
  src, 
  alt, 
  width = '100%', 
  caption 
}) {
  const cdnUrl = `https://cdn.freshshots.io/1/${src}`;
  
  return (
    <figure style={{ margin: '2rem 0' }}>
      <img 
        src={cdnUrl} 
        alt={alt}
        style={{ 
          width, 
          borderRadius: '8px',
          border: '1px solid var(--ifm-color-emphasis-200)'
        }}
      />
      {caption && (
        <figcaption style={{ 
          textAlign: 'center', 
          fontStyle: 'italic',
          marginTop: '0.5rem'
        }}>
          {caption}
        </figcaption>
      )}
    </figure>
  );
}

Usage in MDX:

import FreshShot from '@site/src/components/FreshShot';

# API Authentication

## Setting Up OAuth

<FreshShot 
  src="oauth-setup.png"
  alt="OAuth configuration interface"
  caption="Configure OAuth settings in the developer dashboard"
/>

## Generating API Keys

<FreshShot 
  src="api-key-generated.png" 
  alt="Generated API key display"
  width="600px"
  caption="Your new API key will be displayed once"
/>

Step 4: Advanced Docusaurus Patterns

API Reference with Live Examples:

---
id: users-api
title: Users API
---

# Users API Reference

## GET /api/v1/users

Retrieve a list of users from your account.

### Example Request

```bash
curl -X GET "https://api.yourapp.com/v1/users" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

Authentication Required


**SDK Documentation with Screenshots:**

```mdx
# JavaScript SDK Quick Start

## Installation

```bash
npm install @yourapp/sdk

Basic Usage

import { YourAppSDK } from '@yourapp/sdk';

const client = new YourAppSDK({
  apiKey: 'your-api-key'
});

const users = await client.users.list();
console.log(users);

SDK Console Output


## Advanced Developer Documentation Patterns

### Multi-Environment Documentation

Document different environments:

```json
{
  "action": "visit_page",
  "url": "https://staging-api.yourapp.com/dashboard"
}

Create environment-specific screenshots:

api-dashboard-staging.png
api-dashboard-production.png
api-dashboard-sandbox.png

Error State Documentation

Capture and document error states:

[
  {
    "action": "visit_page",
    "url": "https://api-demo.yourapp.com/console"
  },
  {
    "action": "type_input",
    "selector": "api-key-input",
    "input_value": "invalid-key"
  },
  {
    "action": "click_element",
    "selector": "test-button"
  },
  {
    "action": "take_screenshot",
    "selector": "error-response",
    "save_screenshot_to": "api-auth-error.png"
  }
]

Version-Specific Documentation

Create workflows for different API versions:

[
  {
    "action": "visit_page",
    "url": "https://api-demo.yourapp.com/v2/console"
  },
  {
    "action": "take_screenshot",
    "selector": "v2-interface",
    "save_screenshot_to": "api-v2-interface.png"
  }
]

Docusaurus Build Integration

Automated Screenshot Updates

GitHub Actions Workflow:

name: Update Documentation Screenshots

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  update-docs:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
        
      - name: Wait for deployment
        run: sleep 120
        
      - name: Trigger FreshShots workflows
        run: |
          # API documentation screenshots
          curl -X POST https://api.freshshots.io/v1/run/201 \
            -H "x-api-key: ${{ secrets.FRESHSHOTS_API_KEY }}"
          
          # SDK examples screenshots  
          curl -X POST https://api.freshshots.io/v1/run/202 \
            -H "x-api-key: ${{ secrets.FRESHSHOTS_API_KEY }}"
          
          # Authentication flow screenshots
          curl -X POST https://api.freshshots.io/v1/run/203 \
            -H "x-api-key: ${{ secrets.FRESHSHOTS_API_KEY }}"
        
      - name: Wait for screenshots
        run: sleep 180
        
      - name: Build Docusaurus
        run: |
          npm install
          npm run build
          
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build

Pre-build Screenshot Validation

// scripts/validate-screenshots.js
const axios = require('axios');
const fs = require('fs').promises;

async function validateScreenshots() {
  const screenshotUrls = [
    'https://cdn.freshshots.io/1/api-dashboard-overview.png',
    'https://cdn.freshshots.io/1/api-response-users.png',
    'https://cdn.freshshots.io/1/oauth-setup.png'
  ];
  
  for (const url of screenshotUrls) {
    try {
      const response = await axios.head(url);
      if (response.status !== 200) {
        throw new Error(`Screenshot not available: ${url}`);
      }
      console.log(`✅ ${url}`);
    } catch (error) {
      console.error(`❌ ${url}: ${error.message}`);
      process.exit(1);
    }
  }
  
  console.log('All screenshots validated successfully!');
}

validateScreenshots();

Add to package.json:

{
  "scripts": {
    "validate-screenshots": "node scripts/validate-screenshots.js",
    "build": "npm run validate-screenshots && docusaurus build"
  }
}

Developer Experience Optimization

Screenshot Loading Performance

Optimize screenshot loading in Docusaurus:

// src/components/OptimizedFreshShot.jsx
import React, { useState } from 'react';

export default function OptimizedFreshShot({ src, alt, ...props }) {
  const [loaded, setLoaded] = useState(false);
  const cdnUrl = `https://cdn.freshshots.io/1/${src}`;
  
  return (
    <div style={{ position: 'relative' }}>
      {!loaded && (
        <div style={{ 
          backgroundColor: '#f0f0f0',
          height: '200px',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center'
        }}>
          Loading screenshot...
        </div>
      )}
      <img 
        src={cdnUrl}
        alt={alt}
        onLoad={() => setLoaded(true)}
        style={{ 
          display: loaded ? 'block' : 'none',
          ...props.style 
        }}
        {...props}
      />
    </div>
  );
}

Dark Mode Support

Ensure screenshots work with Docusaurus dark mode:

import { useColorMode } from '@docusaurus/theme-common';

export default function ThemeAwareFreshShot({ src, darkSrc, alt }) {
  const { colorMode } = useColorMode();
  const imageSrc = colorMode === 'dark' && darkSrc ? darkSrc : src;
  const cdnUrl = `https://cdn.freshshots.io/1/${imageSrc}`;
  
  return (
    <img 
      src={cdnUrl} 
      alt={alt}
      style={{
        border: colorMode === 'dark' 
          ? '1px solid #444' 
          : '1px solid #ddd'
      }}
    />
  );
}

Open Source Documentation Best Practices

Contributor Guidelines

Create guidelines for screenshot management:

# Contributing to Documentation

## Screenshot Guidelines

1. **Use FreshShots URLs**: Always use CDN URLs for consistency
2. **Follow naming conventions**: `feature-component-state.png`
3. **Test in staging**: Capture from staging environment first
4. **Update workflows**: Modify FreshShots workflows, don't upload manual screenshots

## Adding New Screenshots

1. Tag UI elements with `data-freshshots-id`
2. Update FreshShots workflow in our account
3. Use CDN URL in documentation
4. Test the documentation build

Community Screenshot Management

For open source projects:

# .github/workflows/community-screenshots.yml
name: Community Screenshot Updates

on:
  pull_request:
    paths: ['docs/**']

jobs:
  check-screenshots:
    runs-on: ubuntu-latest
    steps:
      - name: Check for manual screenshots
        run: |
          if git diff --name-only origin/main...HEAD | grep -E '\.(png|jpg|jpeg|gif)$'; then
            echo "❌ Manual screenshot files detected"
            echo "Please use FreshShots CDN URLs instead"
            exit 1
          fi
          echo "✅ No manual screenshot files found"

Measuring Developer Documentation Success

Analytics Integration

Track screenshot performance:

// src/theme/DocItem/index.js
import React, { useEffect } from 'react';
import OriginalDocItem from '@theme-original/DocItem';

export default function DocItem(props) {
  useEffect(() => {
    // Track screenshot visibility
    const screenshots = document.querySelectorAll('img[src*="freshshots.io"]');
    
    const observer = new IntersectionObserver((entries) => {
      entries.forEach((entry) => {
        if (entry.isIntersecting) {
          // Track screenshot view
          analytics.track('Screenshot Viewed', {
            url: entry.target.src,
            page: window.location.pathname
          });
        }
      });
    });
    
    screenshots.forEach((img) => observer.observe(img));
    
    return () => observer.disconnect();
  }, []);
  
  return <OriginalDocItem {...props} />;
}

Documentation Quality Metrics

Metric	Before FreshShots	After FreshShots
Screenshot accuracy	45% current	100% current
Developer onboarding time	4.2 days average	2.1 days average
API adoption rate	23% try after reading docs	67% try after reading docs
Support tickets	150/month (confusion)	45/month
Documentation maintenance	25 hrs/month	3 hrs/month

Troubleshooting Common Issues

Build failures due to missing screenshots:

Implement screenshot validation in CI
Use fallback images for development
Set up monitoring for CDN availability

Screenshots don’t match current code:

Align FreshShots workflows with deployment pipeline
Use staging environment for testing
Implement webhook notifications for completion

Performance issues with many screenshots:

Implement lazy loading
Use appropriate image sizes
Consider WebP format for better compression

Ready to transform your Docusaurus documentation? Start your free FreshShots account and eliminate manual screenshot management forever.

Building developer tools or API documentation? Contact our team for personalized guidance on documentation automation.