How to Generate Share Cards for Archify Diagrams

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, 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 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:

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:

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: 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. When the format matches "share-card", the viewer executes a dedicated code path:

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 – Manages the share-cue UI that displays progress indicators during export
• 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 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, viewer/template.source.html, and 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.

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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}