# How to Generate Share Cards for Archify Diagrams

> Generate stunning Archify share cards optimized for social media and docs. Learn how to create shareable PNG images easily using the built-in export pipeline or API.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-09-11

---

**Archify generates 1200 × 630 px PNG share cards through a built-in export pipeline that supports both UI-triggered downloads and programmatic API calls.** The feature resides in the `tt-a1i/archify` repository and produces optimized images for social media, documentation, and issue tracking.

The share card system supports three distinct export types: the standard **Share Card**, the **Route Share Card**, and the **Reach Share Card**. Each variant renders the current diagram state to a fixed-dimension canvas and handles naming conventions, error states, and cleanup automatically.

## Understanding the Share Card Export Format

When you initiate a share card export, Archify locks the output dimensions to **1200 × 630 pixels**—the classic social-media card aspect ratio. The viewer sets the internal format identifier to `"share-card"` and records the export parameters for analytics.

In [`viewer/export.js`](https://github.com/tt-a1i/archify/blob/main/viewer/export.js), the constants `SHARE_CARD_WIDTH` and `SHARE_CARD_HEIGHT` define these dimensions explicitly【/cache/repos/github.com/tt-a1i/archify/main/viewer/export.js#L1036-L1039】. The export flow then:

- Generates a PNG blob via the HTML5 Canvas API (`canvas.toBlob`)
- Logs the operation through `recordExportReceipt('share-card', …)`
- Triggers a browser download with a predictable filename pattern

## Generating Share Cards via the User Interface

The simplest method uses the viewer’s **Export → Share Card** menu. This UI element is defined in [`viewer/template.source.html`](https://github.com/tt-a1i/archify/blob/main/viewer/template.source.html) with the data attribute `data-format="share-card"`【/cache/repos/github.com/tt-a1i/archify/main/viewer/template.source.html#L5055】.

To export manually:

1. Open the diagram in the Archify viewer
2. Click **Export** in the top navigation
3. Select **Share Card** (or choose **Reach Share Card** if analyzing upstream/downstream dependencies)
4. Save the PNG when the browser prompts you

If the export fails, the viewer updates the DOM attribute `data-last-export-error-format` so you can inspect the specific error message【/cache/repos/github.com/tt-a1i/archify/main/viewer/export.js#L1095-L1099】.

## Programmatic Share Card Generation

For automation or custom integrations, call the viewer’s export API directly. The `exportToBlob` method accepts a format configuration and returns a `Promise<Blob>`.

### Standard Share Card

Use the base configuration to capture the current viewport:

```javascript
async function exportShareCard() {
  // Force the share‑card format
  const blob = await viewer.exportToBlob({ format: 'share-card' });

  // Build a filename based on the diagram name
  const name = viewer.diagramFilename() + '-share-card.png';

  // Trigger download (the viewer already handles error UI)
  viewer.download(blob, name);
}

```

The resulting filename follows the pattern `<diagram-base>-share-card.png`【/cache/repos/github.com/tt-a1i/archify/main/viewer/export.js#L1087-L1093】.

### Reach Share Card Variant

For dependency analysis, specify the `reach` variant and a direction. This requires an active reach query in the viewer:

```javascript
async function exportReachShareCard(direction) {
  const blob = await viewer.exportToBlob({
    format: 'share-card',
    variant: 'reach',
    direction,            // 'upstream' or 'downstream'
  });

  const name = `${viewer.diagramFilename()}-${direction}-reach-share-card.png`;
  viewer.download(blob, name);
}

```

The **Reach Share Card** adheres to strict "fail-closed" rules defined in [`docs/research-reach-share-card-2026-07-23.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-reach-share-card-2026-07-23.md): it fails if the closure is empty or the direction is invalid, and it copies the resolved reach state without performing new graph traversal during export【/cache/repos/github.com/tt-a1i/archify/main/docs/research-reach-share-card-2026-07-23.md#L27-L34】.

## Technical Implementation Details

The core logic resides in [`viewer/export.js`](https://github.com/tt-a1i/archify/blob/main/viewer/export.js). When the format matches `"share-card"`, the viewer executes a dedicated code path:

```javascript
if (format === 'share-card') {
  // Record receipt for analytics / debugging
  recordExportReceipt('share-card', blob, true, {
    width: SHARE_CARD_WIDTH,
    height: SHARE_CARD_HEIGHT,
  });
  // Prompt the user to download the PNG
  download(blob, base + '-share-card.png');
}

```

For reach variants, the pipeline appends `direction` and `reach` flags before invoking `download`【/cache/repos/github.com/tt-a1i/archify/main/viewer/export.js#L1111-L1112】.

Supporting modules include:

- **[`viewer/guided-views.js`](https://github.com/tt-a1i/archify/blob/main/viewer/guided-views.js)** – Manages the share-cue UI that displays progress indicators during export
- **[`viewer/export-cleanup.js`](https://github.com/tt-a1i/archify/blob/main/viewer/export-cleanup.js)** – Removes temporary artifacts after PNG generation, ensuring the output is a clean snapshot

## Summary

- **Archify share cards** are fixed at 1200 × 630 px, ideal for social media and documentation.
- **Two export paths** exist: the Export menu in [`template.source.html`](https://github.com/tt-a1i/archify/blob/main/template.source.html) and the programmatic `exportToBlob` API.
- **Three variants** are available: standard Share Card, Route Share Card, and Reach Share Card (upstream/downstream).
- **Error handling** uses `data-last-export-error-format` to surface failures in the UI.
- **Source files** implementing this feature include [`viewer/export.js`](https://github.com/tt-a1i/archify/blob/main/viewer/export.js), [`viewer/template.source.html`](https://github.com/tt-a1i/archify/blob/main/viewer/template.source.html), and [`viewer/export-cleanup.js`](https://github.com/tt-a1i/archify/blob/main/viewer/export-cleanup.js).

## Frequently Asked Questions

### What file format does Archify use for share cards?

Archify exports share cards as PNG images. The viewer uses the HTML5 Canvas API to render the diagram and converts it to a PNG blob via `canvas.toBlob`. The exact dimensions are hardcoded to 1200 pixels wide by 630 pixels tall in [`viewer/export.js`](https://github.com/tt-a1i/archify/blob/main/viewer/export.js).

### Can I automate share card generation for multiple diagrams?

Yes. The viewer exposes the `exportToBlob` method on the global viewer instance. You can script batch exports by calling this method with `format: 'share-card'` and handling the returned blob to upload to storage or attach to tickets programmatically.

### Why does the Reach Share Card require a direction parameter?

The Reach Share Card visualizes dependency chains—either upstream (dependencies) or downstream (dependents). According to the design specification in [`docs/research-reach-share-card-2026-07-23.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-reach-share-card-2026-07-23.md), the export fails if you provide an invalid direction or if the reach query returns an empty result set, ensuring you never share misleading blank diagrams.