Skip to content
Back to search

share-cards

SkillWorks with Claude CodeGitHub

Make link-preview images (1200x630 Open Graph cards) for every page of a website from one HTML template, and write each page's own title, description, canonical address and image tags into its HTML at build time, so links shared in chat apps and on social sites show the right preview even for single-page apps. Use whenever the user wants Open Graph images, OG cards, social cards, share images, link previews, "the preview when I paste my link", twitter cards, og:image or meta tags per page, or says a shared link shows the wrong title or picture, the same preview for every page, or no preview at all.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 21 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/VinVirtual/share-cards with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/VinVirtual/share-cards'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vinvirtual--share-cards/badge.svg)](/listings/vinvirtual--share-cards)

HTML

<a href="/listings/vinvirtual--share-cards"><img src="/api/listings/vinvirtual--share-cards/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/VinVirtual/share-cards ~/.claude/skills/share-cards
npm i -g playwright-core          # or: npm i -D playwright-core in your project
~/.claude/skills/share-cards/cards check

`cards check` reports which copy of playwright-core and which browsers it found, and starts one to prove it works. Two environment variables override the search: `CARDS_PLAYWRIGHT` (path to playwright-core) and `CARDS_CHROME` (path to a Chromium-based browser). If no browser starts and `TMPDIR` points at a very long path, shorten it: Chrome keeps sockets there and their paths have a length limit.

The commands below are written as `cards`; use the full path, an alias, or `npm i -D /path/to/share-cards` and `npx cards`. `cards` is a small bash launcher; where bash is missing, run `node lib/cli.mjs` instead.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 53 lines
  1. ---
  2. name: share-cards
  3. description: Make link-preview images (1200x630 Open Graph cards) for every page of a website from one HTML template, and write each page's own title, description, canonical address and image tags into its HTML at build time, so links shared in chat apps and on social sites show the right preview even for single-page apps. Use whenever the user wants Open Graph images, OG cards, social cards, share images, link previews, "the preview when I paste my link", twitter cards, og:image or meta tags per page, or says a shared link shows the wrong title or picture, the same preview for every page, or no preview at all.
  4. ---
  5. # share-cards
  6. Preview crawlers (chat apps, social sites, search) read the HTML a server sends and **do not run JavaScript**. A single-page app sends the same HTML for every address, so every link shows the same preview. share-cards fixes both halves:
  7. 1. **render**: one HTML template + a list of pages → one 1200x630 JPEG per page, drawn in a headless browser.
  8. 2. **inject**: the built `index.html` → one HTML file per page, each with its own `<title>`, description, canonical, `og:*` and `twitter:*` tags.
  9. Skill folder: `~/.claude/skills/share-cards/` (written below as `$S`). Every command is `$S/cards <command> [dir]`, where `[dir]` holds `cards.config.json`. `$S/cards help` lists them.
  10. ```
  11. $S/cards the command line
  12. $S/lib/ config, tag injection, rendering, verify, preview, rewrites
  13. $S/templates/ editorial.html, minimal.html, technical.html, runtime.js
  14. $S/vite-plugin.mjs runs inject after `vite build`
  15. $S/references/templates.md slots, variables, and how to write your own template
  16. $S/examples/site/ a 4-page example with its cards and injected pages
  17. $S/README.md config reference, framework notes, limits
  18. ```
  19. ## Workflow
  20. 1. **Check the machine**: `$S/cards check`. Only `render` and `preview` need a browser.
  21. 2. **Find the pages.** Read the project's router or content folder and list every public address. Find where static files are served from (`public/`, `static/`) and where the build goes (`dist/`, `build/`, `out/`).
  22. 3. **Scaffold**: `$S/cards init <project>` (add `--mjs` when the page list should be built from the project's own route or content data, so it cannot drift). Set `siteUrl` (the real `https://` origin), `siteName`, `imageDir` (inside the static folder, e.g. `public/og`), `imageUrlPath` (where that folder is served, e.g. `/og`) and `dist`.
  23. 4. **Write each page's entry**:
  24. - `title`: the full page title as it should appear in the preview.
  25. - `description`: one sentence, 160 characters at most.
  26. - `cardTitle`: the words drawn on the card. Keep it short (about 2 to 6 words). `*stars*` mark words drawn in the accent colour.
  27. - `cardDescription` (optional, a shorter line for the card), `kicker` (small label), `art` (an image file from the project), `template` (per-page override).
  28. - Never invent facts, numbers or quotes for these. Take the words from the page itself.
  29. 5. **Pick a template and theme.** `editorial` (paper, heavy serif), `minimal` (white, quiet), `technical` (dark, monospace). Set `theme` to the project's own colours. For anything else run `$S/cards eject <name> card.html`, edit it, and set `"template": "./card.html"`. See `references/templates.md`.
  30. 6. **Render**: `$S/cards render <project>`. Read every warning: a cut-off title or description means the text must be shortened.
  31. 7. **Look at the result.** `$S/cards preview <project>` writes `cards-preview/contact-sheet.png` and `chat-preview.png`. **Read both PNGs.** Check each card for cut-off words, crowding, weak contrast and art that hides text. Fix and render again. Do not tell the user the cards look right unless you have looked.
  32. 8. **Prepare the page shell.** `inject` fills tags that already exist and fails if one is missing. Run `$S/cards tags <project>` and paste the block into the `<head>` of the source `index.html`, replacing any old share tags (or pass `--add-missing`).
  33. 9. **Wire it into the build**:
  34. - Vite: add `shareCards()` from `$S/vite-plugin.mjs` to `plugins` (see README).
  35. - Anything else: run `$S/cards inject <project>` after the build command.
  36. 10. **Host rules**: if the host has a catch-all rewrite to `/index.html`, print page rules with `$S/cards rewrites vercel|netlify|netlify-toml <project>` and place them **before** the catch-all. Show the user the rules; do not edit host config without saying so.
  37. 11. **Verify**: build the site, then `$S/cards verify <project>`. It must end with `All good.`
  38. 12. **Tell the user what is left**: deploy, then paste one real link into a chat app. Previews are cached by each app, sometimes for days; set `"versionImages": true` to change the image address whenever a card changes.
  39. ## Rules
  40. - `siteUrl` must be the production origin. Preview images need absolute `https://` addresses.
  41. - Render cards before the build so the build copies them, and commit the cards and `cards.lock.json`. CI then needs no browser.
  42. - Nothing is fetched from the network while rendering unless the config sets `"allowNetwork": true`. Web fonts must be local files listed under `fonts`.
  43. - Fonts default to system stacks, so cards drawn on another machine can differ. For identical output everywhere, add font files to the project (check their licence) and list them under `fonts`.
  44. - Say plainly what was not checked: the real crawler of each app, and the host's routing once deployed.
README.md · README · 284 lines
  1. # share-cards
  2. Link-preview images and per-page share tags for every page of a website, from one HTML template.
  3. ![Four example cards: two editorial, one technical, one minimal](examples/site/cards-preview/contact-sheet.png)
  4. When someone pastes a link into a chat app or a social site, that app fetches the page and reads a few tags in its `<head>`: the title, the description and the address of a preview image. These crawlers **do not run JavaScript**. A single-page app sends the same HTML for every address, so every link shows the same title and the same picture, or none.
  5. share-cards does two things at build time:
  6. - **Draws a 1200×630 card for every page** from one HTML/CSS template, using a headless browser.
  7. - **Writes one HTML file per page** from your built `index.html`, each with its own `<title>`, description, canonical address, `og:*` and `twitter:*` tags.
  8. It is packaged as a [Claude Code](https://claude.com/claude-code) skill (`SKILL.md` tells the assistant how to use it) and works the same by hand from the command line.
  9. ## How it works
  10. | Stage | What happens | Sample |
  11. |---|---|---|
  12. | 1. List | You list each page once in `cards.config.json`. | `{ "path": "/visit", "title": "Visit \| Quillmoss Tool Library", "cardTitle": "Find the *front desk*" }` |
  13. | 2. Render | A headless browser fills the template and saves a JPEG per page. Unchanged cards are skipped by content hash (config text, template, the local files its `src` and `href` point at, art, logo, fonts). Files reached only from inside CSS are not tracked: use `--force` after changing one. | `drew /visit -> dist/og/visit.jpg (53 KB)` |
  14. | 3. Inject | The built page shell is copied once per page with that page's tags filled in. | `<meta property="og:image" content="https://quillmoss.example/og/visit.jpg" />` |
  15. | 4. Verify | Sizes, weights, lengths, escaping and addresses are checked before you deploy. | `4 pages checked, cards total 268 KB, built pages checked` |
  16. ## Requirements
  17. | Needed | Why | Licence |
  18. |---|---|---|
  19. | Node.js 18 or newer | runs everything | MIT |
  20. | [playwright-core](https://www.npmjs.com/package/playwright-core) | drives the browser (`render` and `preview` only) | Apache-2.0 |
  21. | Google Chrome, Chromium, Microsoft Edge or Playwright's own Chromium | draws the cards | their own licences |
  22. None of these is included in this repository. `inject`, `verify`, `rewrites` and `tags` need only Node.
  23. No fonts are bundled. The built-in templates use system font stacks, and nothing is fetched from a network while rendering unless you opt in (see [Fonts](#fonts)).
  24. ## Install
  25. ```bash
  26. git clone https://github.com/VinVirtual/share-cards ~/.claude/skills/share-cards
  27. npm i -g playwright-core # or: npm i -D playwright-core in your project
  28. ~/.claude/skills/share-cards/cards check
  29. ```
  30. `cards check` reports which copy of playwright-core and which browsers it found, and starts one to prove it works. Two environment variables override the search: `CARDS_PLAYWRIGHT` (path to playwright-core) and `CARDS_CHROME` (path to a Chromium-based browser). If no browser starts and `TMPDIR` points at a very long path, shorten it: Chrome keeps sockets there and their paths have a length limit.
  31. The commands below are written as `cards`; use the full path, an alias, or `npm i -D /path/to/share-cards` and `npx cards`. `cards` is a small bash launcher; where bash is missing, run `node lib/cli.mjs` instead.
  32. ## Quick start
  33. ```bash
  34. cd my-site
  35. cards init # writes cards.config.json; edit the pages
  36. cards render # draws public/og/*.jpg
  37. cards preview # cards-preview/contact-sheet.png and chat-preview.html: look at them
  38. cards tags # prints the <head> tags; paste them into your source index.html
  39. npm run build # your normal build
  40. cards inject # writes dist/<page>/index.html for every page
  41. cards verify # must end with "All good."
  42. ```
  43. ## Commands
  44. | Command | What it does |
  45. |---|---|
  46. | `cards check` | Is Node, playwright-core and a browser ready? |
  47. | `cards init [dir] [--mjs]` | Write a starter `cards.config.json` (or `cards.config.mjs`). |
  48. | `cards render [dir]` | Draw every card that changed. `--force` redraws all, `--only /path` limits it (repeatable), `--jobs 3` sets how many pages are open at once. |
  49. | `cards inject [dir]` | Read `<dist>/index.html` and write one HTML file per page. `--dist d`, `--html file` (a different shell), `--out d` (write elsewhere), `--add-missing`. |
  50. | `cards verify [dir]` | Check cards, text and built pages. `--no-html` skips built pages, `--require-html` fails if there are none. |
  51. | `cards preview [dir]` | Write `cards-preview/contact-sheet.png`, `chat-preview.html` and `chat-preview.png`. |
  52. | `cards build [dir]` | `render`, then `inject`, then `verify`. |
  53. | `cards rewrites <vercel\|netlify\|netlify-toml> [dir]` | Print host rules. `--spa` adds a catch-all to `/index.html` at the end. |
  54. | `cards tags [dir]` | Print the `<head>` tags a page shell needs. |
  55. | `cards eject <template> [file]` | Copy a built-in template to edit. |
  56. | `cards test` | Run the unit tests. |
  57. `[dir]` is the folder that holds the config (default: the current folder), or the config file itself. Paths inside the config are relative to that folder.
  58. ## Config
  59. ```json
  60. {
  61. "siteUrl": "https://example.com",
  62. "siteName": "Example Site",
  63. "template": "editorial",
  64. "logo": "public/logo.svg",
  65. "theme": { "accent": "#d8401f" },
  66. "imageDir": "public/og",
  67. "imageUrlPath": "/og",
  68. "dist": "dist",
  69. "pages": [
  70. {
  71. "path": "/pricing",
  72. "title": "Pricing | Example Site",
  73. "description": "One sentence, 160 characters at most.",
  74. "cardTitle": "Simple *pricing*",
  75. "kicker": "Plans",
  76. "art": "public/img/pricing.jpg",
  77. "template": "minimal"
  78. }
  79. ]
  80. }
  81. ```
  82. | Setting | Default | Meaning |
  83. |---|---|---|
  84. | `siteUrl` | required | The production origin. Preview images need absolute addresses, so this must be the real `https://` address. |
  85. | `siteName` | required | Shown on cards and written to `og:site_name`. |
  86. | `template` | `editorial` | `editorial`, `minimal`, `technical`, or a path to your own `.html` file. |
  87. | `logo` | none | An image drawn on every card. |
  88. | `theme` | `{}` | CSS variables for the template: `accent`, `background`, `text`, `muted`, `fontDisplay` and others. See [references/templates.md](references/templates.md). |
  89. | `fonts` | `[]` | Local font files to load: `{ "family", "file", "weight", "style" }`. |
  90. | `imageDir` | `public/og` | Where the JPEGs are written. Use a folder your build copies into the site. |
  91. | `imageUrlPath` | `/og` | The address that folder is served at. |
  92. | `dist` | `dist` | The built site that `inject` and `verify` read. |
  93. | `width`, `height` | `1200`, `630` | Card size in pixels. The built-in templates are designed for the default. |
  94. | `quality` | `88` | JPEG quality, 1 to 100. |
  95. | `maxImageKB` | `300` | `verify` fails a card heavier than this. |
  96. | `versionImages` | `false` | Add `?v=<hash>` to image addresses so apps that cache previews fetch a changed card. |
  97. | `allowNetwork` | `false` | Let templates load files from the network while rendering. |
  98. Each page:
  99. | Setting | Meaning |
  100. |---|---|
  101. | `path` | Required. The address without the origin: `/`, `/pricing`, `/guides/first-loan`. |
  102. | `title` | Required. Goes into `<title>`, `og:title` and `twitter:title`. |
  103. | `description` | Required. Goes into the description tags. `verify` fails over 160 characters. |
  104. | `cardTitle` | The words drawn on the card (default: `title`). `*Stars*` mark words drawn in the accent colour. |
  105. | `cardDescription` | The line drawn under it (default: `description`). |
  106. | `kicker` | A small label above the title. |
  107. | `art` | An image file drawn on the card. |
  108. | `template` | A different template for this page. |
  109. | `image` | The image file name without `.jpg` (default: from the path, `/guides/first-loan` → `guides-first-loan`, `/` → `home`). |
  110. A `cards.config.mjs` may `export default` the same object, or a function that returns it, so the page list can be built from your own routes or content files:
  111. ```js
  112. import { posts } from './src/content/posts.js'
  113. export default {
  114. siteUrl: 'https://example.com',
  115. siteName: 'Example Site',
  116. pages: [
  117. { path: '/', title: 'Example Site', description: 'What the site is, in one sentence.' },
  118. ...posts.map((post) => ({ path: `/posts/${post.slug}`, title: `${post.title} | Example Site`, cardTitle: post.title, description: post.summary, kicker: 'Post' })),
  119. ],
  120. }
  121. ```
  122. ## Templates
  123. Three built-in templates, each a different layout and type treatment:
  124. - **editorial**: warm paper, a masthead rule and a heavy serif headline. Art fills the right edge; without art there is an accent disc and an ink ring.
  125. - **minimal**: near-white, one weight of sans, a single accent dot. Art sits in a tall rounded frame.
  126. - **technical**: near-black with a drafting grid, monospace labels and corner marks. Art sits in a square framed panel; without art there is a drawn scope.
  127. Templates are plain HTML and CSS. Elements marked `data-slot="title"` (and `kicker`, `description`, `site`, `domain`, `path`, `address`, `logo`, `art`) are filled in, and `theme` values become CSS variables. Titles shrink to fit; one that cannot fit even at the smallest size is cut at a word with an ellipsis and `render` warns you. A description that does not fit also produces a warning.
  128. [references/templates.md](references/templates.md) lists every slot and variable and explains how to write your own.
  129. ### Fonts
  130. - By default the templates use system font stacks. Nothing is bundled and nothing is downloaded. Cards drawn on a different machine can therefore use different fonts.
  131. - For the same result everywhere, add font files to your project and list them under `fonts`. Check the licence of any font you commit; the SIL Open Font License and Apache-2.0 both allow it when the notice travels with the files.
  132. - Network requests are blocked while rendering and reported as warnings. `"allowNetwork": true` turns that off.
  133. ## Look before you ship
  134. `cards preview` writes:
  135. - `cards-preview/contact-sheet.png`: every card with its page, template and file size.
  136. - `cards-preview/chat-preview.html` (and a `.png` of it): each page as a link pasted into a made-up chat thread, light and dark, with the title and description cut the way previews usually cut them.
  137. It is an imitation. Real apps crop, trim and cache in their own ways.
  138. ## What `verify` checks
  139. - Every page has a card, it is a JPEG of exactly `width`×`height`, and it weighs no more than `maxImageKB`.
  140. - Every card matches the current config and template (a stale card fails; run `cards render`).
  141. - Descriptions are 160 characters or fewer. Titles over 70 characters get a warning.
  142. - Image addresses are absolute `https://` addresses.
  143. - In the built site, every page has its own HTML file, and its title, description, canonical, `og:*` and `twitter:*` values read back exactly as written in the config. An unescaped quote, which would cut a value short, fails this check.
  144. - A warning if the card files are not inside the built site.
  145. ## Framework notes
  146. ### Vite
  147. ```js
  148. // vite.config.js
  149. import shareCards from 'share-cards/vite' // or a relative path to vite-plugin.mjs
  150. export default {
  151. plugins: [shareCards()], // options: { config: '.', addMissing: false }
  152. }
  153. ```
  154. The plugin runs after a successful `vite build`, reads `cards.config.json` from the Vite root and writes the per-page files into Vite's `build.outDir`. It does not draw cards: run `cards render` before the build with `imageDir` set to a folder inside `public/`, and commit the JPEGs and `cards.lock.json`. CI then needs no browser.
  155. ### Plain static sites and other build tools
  156. Run `cards inject` after your build:
  157. ```json
  158. { "scripts": { "build": "your-build-command && cards inject" } }
  159. ```
  160. `inject` needs one built HTML file to copy (`<dist>/index.html`, or `--html`). If your generator already writes a separate HTML file per page, it can write these tags itself; you can still use `render` for the images and `verify --no-html` for the checks, or import `withPageMeta` from `lib/index.mjs` to fill tags in your own script.
  161. The page shell must already contain the tags to fill. `cards tags` prints them. `inject` stops with a list of the missing tags rather than writing a page that previews badly; `--add-missing` adds them before `</head>` instead.
  162. ### Host rewrites
  163. After `inject`, `/visit` exists as `visit/index.html`. Many static hosts serve that on their own. You need explicit rules when a catch-all rewrite sends every address to `/index.html`, which is the usual single-page-app setup, and on some hosts would win over the page files. Put the page rules **before** the catch-all.
  164. ```bash
  165. cards rewrites vercel # a "rewrites" list for vercel.json
  166. cards rewrites netlify # lines for a _redirects file
  167. cards rewrites netlify-toml # [[redirects]] blocks for netlify.toml
  168. ```
  169. ```json
  170. {
  171. "rewrites": [
  172. { "source": "/visit", "destination": "/visit/index.html" }
  173. ]
  174. }
  175. ```
  176. ```
  177. /visit /visit/index.html 200
  178. ```
  179. Add `--spa` to append the catch-all (`/(.*)` → `/index.html` for Vercel, `/* /index.html 200` for Netlify) after the page rules. The helper only prints; you paste the result into your host config.
  180. ## Example
  181. [`examples/site`](examples/site) is a four-page single-page app for a made-up tool library:
  182. ```
  183. examples/site/
  184. cards.config.json the four pages, three templates
  185. art/ logo and two drawings (SVG)
  186. cards.lock.json content hashes of the rendered cards
  187. dist/ the "built" site
  188. index.html the page shell, with the home page's tags
  189. app.js, style.css the app; it picks the page from the address
  190. og/*.jpg the four cards
  191. catalogue/index.html written by `cards inject`
  192. how-it-works/index.html
  193. visit/index.html
  194. cards-preview/ contact sheet and chat preview
  195. ```
  196. To rebuild it: `cards build examples/site && cards preview examples/site`. To see the site, serve `examples/site/dist` with any static server. The address `quillmoss.example` is not a real site, so its links cannot be tested in a real app.
  197. ## Tests
  198. ```bash
  199. cards test
  200. ```
  201. 69 unit tests run with `node --test` and need no browser: tag injection, escaping, missing-tag failures, incremental hashing, config validation, rewrite rules, image-size reading, the verify checks, browser launch retries (with a fake browser) and the Vite plugin hooks. One test checks that the committed example pages are exactly what `inject` produces.
  202. ## Limits and what has not been tested
  203. - **Real crawlers were not tested.** The tags follow the Open Graph and Twitter card conventions, and the example pages were fetched without JavaScript to confirm the tags are in the HTML. No link was pasted into a real chat app or social site, because the example address is not a real site.
  204. - **Host rewrites were not tested on a deployed site.** The printed rules follow each host's config format as understood when this was written. They were not checked against a live deploy, so check the first one.
  205. - **Tested on Linux with Google Chrome and Node 24**, and the Vite plugin with Vite 6. macOS and Windows are handled in the code (browser paths, path separators) but have not been run. Node 18 to 22 have not been run.
  206. - **Fonts differ between machines** unless you supply font files, so a card drawn on a laptop and in CI can differ. Render in one place and commit the result.
  207. - **Layout is automatic within limits.** A very long title is cut with an ellipsis and a warning. Read the contact sheet.
  208. - **JPEG only**, one size per page. No per-network variants (square or tall).
  209. - **Previews are cached** by the apps that show them, sometimes for days. `versionImages` changes the image address when a card changes; the app decides when to fetch the page again.
  210. - The HTML is edited with pattern matching, not a full parser. It expects ordinary `<meta>`, `<link>` and `<title>` tags in the head; a share tag inside an HTML comment would also be filled.
  211. - The browser is started with its sandbox on. As root, in Docker or in some CI runners Chrome refuses to start that way; `cards check` shows the error. Render on your own machine and commit the images, or run as a normal user.
  212. - `share-cards` is not on npm. Install it from the clone (`npm i -D /path/to/share-cards`) to use the Vite plugin.
  213. ## Licence
  214. MIT, see [LICENSE](LICENSE). The example drawings in `examples/site/art` were made for this repository and are under the same licence.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.