Index

Functions

`runCapture`

async function runCapture(docsDir: string, options: CaptureOptions): Promise<CaptureReport>

TypeScript

Use runCapture to scan your MDX docs, capture screenshots of every <Screenshot> directive, and write the results to disk in a single pipeline call.

Reach for this when you want to automate screenshot generation as part of a build or CI step — after running skrypt generate, call runCapture to populate the visual assets your doc site references.

It walks docsDir for MDX files, parses each <Screenshot> tag, spins up a headless browser to capture the target URLs, and optionally skips unchanged screenshots using a hash comparison. The final output includes a manifest and hash store alongside the image files, so subsequent runs only re-capture what changed.

Parameters

Name	Type	Required	Description
`docsDir`	`string`	Yes	Path to the directory containing your generated MDX files. Scanned recursively for `<Screenshot>` directives.
`options.baseUrl`	`string`	Yes	Root URL of the running doc site to capture — must be reachable before the pipeline starts, or the call throws.
`options.outputDir`	`string`	Yes	Directory where captured `.png` files, the manifest, and the hash store are written. Created if it doesn't exist.
`options.diff`	`boolean`	No	When `true`, skips re-capturing screenshots whose content hash hasn't changed since the last run. Speeds up incremental builds significantly.
`options.viewport`	`{ width: number; height: number }`	No	Browser viewport size for all captures. Defaults to `1280×800`.
`options.timeout`	`number`	No	Milliseconds to wait for each page to load before the capture fails. Defaults to `30000`.

Returns

Returns a CaptureReport object. Use report.captured to see which screenshots were newly written, report.skipped for unchanged files (diff mode), and report.failed for any URLs that couldn't be reached or timed out — surface these as build errors in CI.

Heads up

The pipeline validates that options.baseUrl is reachable before opening the browser. If your dev server isn't running yet, the call will throw immediately rather than failing per-screenshot.
Hash comparison in --diff mode is based on pixel content, not file metadata — renaming a screenshot component without changing the page will still be treated as unchanged.

Example:

const { resolve } = require("path");

// Inline types — do not import from autodocs
/**
 * @typedef {{ baseUrl: string; outputDir: string; diff?: boolean; viewport?: { width: number; height: number }; timeout?: number }} CaptureOptions
 * @typedef {{ captured: string[]; skipped: string[]; failed: { url: string; reason: string }[]; durationMs: number }} CaptureReport
 */

// Mock implementation for demonstration
async function runCapture(docsDir, options) {
  console.log(`Scanning MDX files in: ${resolve(docsDir)}`);
  console.log(`Base URL: ${options.baseUrl}`);
  console.log(`Output dir: ${options.outputDir}`);
  console.log(`Diff mode: ${options.diff ?? false}`);

  // Simulated pipeline result
  return {
    captured: [
      "docs/quickstart/hero.png",
      "docs/api-reference/auth-flow.png",
    ],
    skipped: [
      "docs/guides/installation.png",
    ],
    failed: [],
    durationMs: 4821,
  };
}

async function main() {
  /** @type {CaptureOptions} */
  const options = {
    baseUrl: "http://localhost:3000",
    outputDir: "./public/screenshots",
    diff: true,
    viewport: { width: 1440, height: 900 },
    timeout: 30000,
  };

  try {
    /** @type {CaptureReport} */
    const report = await runCapture("./content/docs", options);

    console.log(`\nCapture complete in ${report.durationMs}ms`);
    console.log(`  Captured : ${report.captured.length} screenshots`);
    console.log(`  Skipped  : ${report.skipped.length} unchanged`);
    console.log(`  Failed   : ${report.failed.length}`);

    if (report.failed.length > 0) {
      console.error("\nFailed captures:");
      report.failed.forEach(({ url, reason }) =>
        console.error(`  ${url} — ${reason}`)
      );
      process.exit(1);
    }
  } catch (err) {
    console.error("Pipeline error:", err.message);
    process.exit(1);
  }
}

main();

// Expected output:
// Scanning MDX files in: /projects/my-docs/content/docs
// Base URL: http://localhost:3000
// Output dir: ./public/screenshots
// Diff mode: true
//
// Capture complete in 4821ms
//   Captured : 2 screenshots
//   Skipped  : 1 unchanged
//   Failed   : 0

TypeScript

`printCaptureReport`

function printCaptureReport(report: CaptureReport): void

TypeScript

Use printCaptureReport to display a human-readable summary of a screenshot capture run directly to stdout.

Call this after running your screenshot capture pipeline to give users immediate feedback on how many directives were found, attempted, and succeeded or failed. It's the last step in a typical capture workflow: scan → parse → capture → report.

If no <Screenshot> directives were found in your docs, the function short-circuits and prints a clear "nothing to do" message instead of an empty summary.

Parameters

Name	Type	Required	Description
`report`	`CaptureReport`	Yes	The result object from your capture run — contains counts of directives found, screenshots attempted, and any failures.

Returns

Nothing (void). Output goes directly to stdout, making this suitable for CLI tools and build scripts where you want capture results visible in terminal output or CI logs.

Heads up

This function always writes to stdout — it's not configurable. If you need structured output (e.g., for programmatic use or logging pipelines), read from the report object directly instead of capturing stdout.

Example:

type CaptureReport = {
  directives: number
  attempted: number
  succeeded: number
  failed: string[]
}

function printCaptureReport(report: CaptureReport): void {
  if (report.directives === 0) {
    console.log('\n  No <Screenshot> directives found in docs.\n')
    return
  }

  console.log('\n  Screenshot Capture Report')
  console.log(`  Directives found : ${report.directives}`)
  console.log(`  Attempted        : ${report.attempted}`)
  console.log(`  Succeeded        : ${report.succeeded}`)
  console.log(`  Failed           : ${report.failed.length}`)

  if (report.failed.length > 0) {
    console.log('\n  Failed captures:')
    report.failed.forEach((f) => console.log(`    - ${f}`))
  }

  console.log()
}

// Simulate a completed capture run
const report: CaptureReport = {
  directives: 5,
  attempted: 5,
  succeeded: 4,
  failed: ['docs/api/authentication.mdx#line-42'],
}

printCaptureReport(report)

// Expected output:
//
//   Screenshot Capture Report
//   Directives found : 5
//   Attempted        : 5
//   Succeeded        : 4
//   Failed           : 1
//
//   Failed captures:
//     - docs/api/authentication.mdx#line-42

TypeScript

heal — capture

Index

Functions

runCapture

printCaptureReport

`runCapture`

`printCaptureReport`