How to Generate Archify Share Cards for README and Social Media

Archify generates canonical 1200×630 PNG share cards from any validated diagram via an embedded Export button or CLI workflow, ready for embedding in README files and social media posts.

The open-source Archify tool transforms JSON-defined architecture diagrams into production-ready visuals. When you need to generate Archify share cards for documentation or social platforms, the toolchain provides a standardized export format that integrates seamlessly with markdown and CI/CD pipelines.

Render the Diagram

Archify supports two entry points for generating share cards: the interactive viewer or the command-line interface.

Interactive viewer: Open any example HTML file (such as examples/web-app.html) in a browser to load the diagram with full toolbar controls.

CLI renderer: Run the Node.js script to generate the HTML artifact:

node archify/bin/archify.mjs render <your-json>.json out.html

The renderer always injects an Export → Share Card button into the toolbar, regardless of the diagram type (Architecture, Workflow, Sequence, Data-Flow, or Lifecycle). This UI element is defined in archify/renderers/architecture/render-architecture.mjs at lines 1025–1030, where it hooks into the downloadShareCard() function.

Export the Share Card

The toolbar offers three variants for capturing your diagram:

• Copy Share Card – Copies the canonical PNG directly to your clipboard for immediate use.
• Export → Share Card – Downloads the PNG to docs/assets/<diagram-name>-share-card.png.
• Export → Route/Reach Share Card – Appears only after tracing a route or reach analysis; this variant bakes the highlighted path into the final image.

The UI toggles these variants automatically based on your interaction state. The exact logic governing route and reach variants is validated in archify/test/route-share-card.test.mjs and archify/test/reach-share-card.test.mjs.

Locate and Embed the Generated PNG

By default, Archify writes share cards to your repository’s docs/assets/ folder using the naming convention <diagram-name>-share-card.png. This location is referenced directly in the project README: "One file, ready to trust and share … self-contained HTML plus PNG, SVG, WebM, and 1200×630 share cards" (line 20).

Embed the asset in any markdown file using standard image syntax:

![MCO runtime share card](docs/assets/mco-runtime-share-card.png)

This syntax works identically for GitHub READMEs, release notes, and social platforms that accept direct PNG URLs.

Automate Share Card Generation in CI/CD

You can script the CLI to generate share cards automatically during your build process, ensuring documentation stays synchronized with diagram changes. The archify/test/share-card-export.test.mjs file demonstrates the minimal sequence required: render the HTML, trigger the rasterization, and capture the output file (lines 36–44).

Example CI workflow:

DIAGRAM=web-app.architecture.json
OUT_DIR=docs/assets

# Render the diagram

node archify/bin/archify.mjs render $DIAGRAM $OUT_DIR/$DIAGRAM.html

# The share card is now available at:

# $OUT_DIR/$(basename $DIAGRAM .json)-share-card.png

git add $OUT_DIR/*.png
git commit -m "Update share cards for $DIAGRAM"

Summary

• Archify produces 1200×630 PNG share cards from any validated diagram type.
• Access exports via the toolbar button defined in archify/renderers/architecture/render-architecture.mjs or automate via CLI.
• Variants include standard, route-traced, and reach-traced share cards for different visual contexts.
• Output files land in docs/assets/ and follow the naming pattern <diagram-name>-share-card.png.

Frequently Asked Questions

What are the exact dimensions of an Archify share card?

Archify renders share cards at exactly 1200×630 pixels, the standard Open Graph image size optimal for social media previews and README badges.

Can I generate share cards without using the interactive viewer?

Yes. Run node archify/bin/archify.mjs render <diagram>.json out.html to generate the HTML, then use a headless browser automation script (as demonstrated in archify/test/share-card-export.test.mjs) to trigger the downloadShareCard() function programmatically.

How do route-traced share cards differ from standard ones?

Route and reach share cards highlight specific paths through your architecture diagram. After tracing a route or reach analysis in the UI, the Export menu automatically toggles to "Route/Reach Share Card" variants, baking the highlighted path into the final PNG without manual screenshot editing.

Where does Archify save the generated PNG files?

The renderer writes files to your repository's docs/assets/ directory using the pattern <diagram-name>-share-card.png, making them easy to version control and reference in markdown documentation.

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