docs: publish the VitePress guide, with a social card - #34
Merged
Conversation
1280x640 on the BtravStack template: near-black canvas, the record mark with an accent glow, the wordmark in entity's accent, tagline and site URL. Rendered from a committed source template — the sibling repos ship only the PNG, so their cards cannot be re-edited. The render is a script rather than a one-liner because Chrome 145 needs two workarounds, both measured and documented inline: new headless never exits after --screenshot, and --window-size is the window rather than the viewport, so it silently clipped the footer off the bottom of the card. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
og:image pointed at logo-light.svg with twitter:card=summary. SVG is not a valid Open Graph image — X, Slack, LinkedIn and Discord all refuse it, so the site had no link preview at all. Points at og-entity.png, switches to summary_large_image, and declares the card's measured 1280x640. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR finalizes publishing the docs/ VitePress guide for @btravstack/entity and updates the site metadata to use a proper PNG Open Graph/Twitter social card so link previews render correctly across platforms.
Changes:
- Adds an
og:carddocs workspace script plus a renderer (docs/og/render.sh) to generate the committed social-card PNG from an HTML source. - Introduces
docs/og/card.htmlas the editable source template for the social card (rendered todocs/public/og-entity.png). - Updates VitePress
headmetadata to point Open Graph/Twitter tags at the PNG and declare the measured 1280×640 size.
Reviewed changes
Copilot reviewed 4 out of 5 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs/package.json | Adds an og:card script for regenerating the committed OG image. |
| docs/og/render.sh | Adds a Chrome+scripting-based renderer and top-crop step to produce a stable 1280×640 PNG. |
| docs/og/card.html | Adds the HTML/CSS source used to render the social card. |
| docs/.vitepress/config.ts | Switches OG/Twitter metadata from SVG to PNG and declares correct card dimensions. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Drops the card's HTML source and render script. The card is generated once and committed, exactly as og-unthrown.png, og-amqp-contract.png and og-temporal-contract.png are — no build tooling in the docs workspace. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Publishes
docs/as a VitePress site at https://btravstack.github.io/entity/, and gives it a working link preview.The site
The guide, organised by the four Diátaxis modes —
tutorial/,how-to/,reference/,explanation/— with one shared sidebar so any page reaches any other. TypeDoc generatesdocs/api/entity/at build time. Deployment runs from.github/workflows/deploy-docs.ymlonce CI is green onmain.TypeDoc runs from
docs/rather than frompackages/entity/, against its own TypeScript from a named catalog: the default catalog'stypescript: 7.0.2is the native port and ships no JS compiler API, so TypeDoc cannot run against it. The reason is inline inpnpm-workspace.yaml.The social card
og:imagepointed atlogo-light.svgwithtwitter:card: summary. SVG is not a valid Open Graph image — X, Slack, LinkedIn and Discord all refuse to render one — so the site had no link preview at all, not merely a small one.Adds
docs/public/og-entity.png, 1280×640, on the same template asog-unthrown.png,og-amqp-contract.pngandog-temporal-contract.png: near-black canvas, the entity record mark with an accent glow, the wordmark in entity's accent, tagline, site URL, and the "Part of BtravStack" footer. Every colour and face is the value of an@btravstack/themetoken — canvas--bg, wordmark in entity's--accent#EE9CC4, "Btrav" in the org--bt-pink#E0589A, Geist for display and JetBrains Mono for the URL.The mark is
logo-dark.svg, the variant meant for a dark canvas: the two files are named for the colour mode they appear in, sologo-light.svg's#33262Cpanel would have all but vanished on#080709.Generated once and committed, exactly as the sibling cards are — no render tooling in the docs workspace.
Then points the metadata at it, switches to
summary_large_image, and declares the card's measured 1280×640. The sibling sites declare 1200×630 while shipping a 1280×640 file; these numbers are the real ones.Verification
Full gate, in CI order:
format --check,lint,typecheck,test,knip,build— all pass. The builtindex.htmlcarries the new tags anddist/og-entity.pngships byte-identical to the source.No changeset: docs-only, nothing changes in
@btravstack/entity's published surface.🤖 Generated with Claude Code