Repository navigation
Share card that survives a square crop, with a versioned URL - #22
Conversation
The card is redrawn by scripts/build-og-card.mjs: the shield, wordmark and line sit inside the centre square, the panel has bevelled corners, and the PNG is 145 KB, under the 300 KB WhatsApp loads. og:image and twitter:image end in ?v= and the first 12 hex of its SHA-256, so a redrawn card is a new URL to every cache. og:locale is en_US.
Crawlers read robots.txt only at the host root, so the root file names every sitemap under it.
|
/craig-review |
There was a problem hiding this comment.
code-reviewer: needs changes
This PR redraws the share card so it survives a square crop and cuts it to about 145 KB. It also versions og:image and twitter:image with a hash of the PNG read at build time, adds og:locale and adds a worktree sitemap line to robots.txt. The direction is sound, but the generator writes og.png before it runs the contrast check, so a failed run still replaces the site's card. The wordmark gradient also looks unlikely to render as the script intends. I could not see astro.config or the route list, so whether Base.astro is ever rendered on demand on Cloudflare is an assumption to check.
Reviewed 95c446c for craig-o-curtis · claude-opus-5-5 · 8 files · left out: pnpm-lock.yaml · $0.21
…wordmark gradient, hash og.png once per build
|
/craig-review |
There was a problem hiding this comment.
code-reviewer follow-up: looks good
Since 95c446c, the contrast check runs before either PNG is written, and the wordmark gradient code that never rendered is gone. The card's hash is now computed once in astro.config.mjs and passed to Base.astro through vite.define, so the layout no longer reads the file system. All three earlier comments are addressed, and the new changes raise no further issues.
Earlier comments
- Fixed; yours to resolve: Contrast gate runs after og.png has already been overwritten
- Fixed; yours to resolve: Wordmark gradient is probably not applied, and its coordinates are offset
- Fixed; yours to resolve: Reading public/og.png with node:fs at render time ties the layout to a build-time, cwd-relative environment
Reviewed 61ece3c (changes since 95c446c) for craig-o-curtis · claude-opus-5-5 · 5 files · $0.13
baldurpan
left a comment
There was a problem hiding this comment.
I re-read this at 61ece3c, after the fixes for craigs-reviewer's three threads, and they hold:
- The contrast check now runs before either
writeFileSync, and the error names both values. - The gradient code and
CYAN_BRIGHTare gone, and nothing inscripts/,context/share-card.mdor the share README still mentions a fade.public/og.pngandassets/share/og-1200x630.pngare both still blob95bbe91, so the card and its?v=080dc75a492bare unchanged. astro.config.mjsresolves the card from its ownimport.meta.url,Base.astrono longer touches the file system, and the**/*include picks upsrc/env.d.ts.
The rest holds up too:
- The panel spans x 299–901, inside the 285–915 square.
- The RGB triples match
packages/theme/tokens.css, and the shield paths matchNorthGuildMark.astroexactly. - The
robots.txtline is within the current CLAUDE.md rule ("Add a line only for a new sitemap"), andhttps://northguild.dev/worktree/sitemap-index.xmlreturns 200. - The Worker already serves
/og.png?v=…asimage/png.
That leaves one naming nit, inline, from context/coding-standards.md. Rename the functions or tell me you'd rather not, and I'll approve either way.
…X-G6) (#478) Closes #448 Closes #456 New OG images: <img width="819" height="424" alt="Image" src="https://github.com/user-attachments/assets/bce3fb5e-d188-44d6-9ae9-e4a778685473" /> Method pages og images: <img width="849" height="436" alt="Image" src="https://github.com/user-attachments/assets/34374576-5bdb-44ea-85ee-a22d477a4596" /> Makes `northguild.dev/gmt/` easier for search engines and AI answer engines to crawl, index and quote. Everything follows documented mechanics: crawlable text, accurate sitemaps, one indexable URL per page, lighter pages, and an `llms.txt` that fits in an agent's context. AI crawlers stay allowed. No `packages/gmt` change and no changeset. ## Search descriptions - No two indexable pages share a meta description. A reference function's description is its TSDoc summary. Where sibling functions share one, a qualifier names the value kind or the namespace. - Each namespace has one written summary. It is both the namespace page's meta description and its line in `llms.txt`, and it replaces 13 identical boilerplate descriptions. - A test on the built site fails when two indexable pages share a description, and lists them. ## Crawling and `llms.txt` - Generated pages carry a real Last updated date from the newest commit of their inputs. The sitemap's `<lastmod>` is copied from that footer date, so the two agree. - A tracked `_headers` file caches hashed `/gmt/_astro/*` files for a year as immutable, and marks the `.md` twins and `llms*.txt` files `noindex`. - The 404 page carries `noindex` and no canonical. - The root `/gmt/llms.txt` fits in 64 KiB (it was about 213 KB). Its Reference section links one `llms.txt` per namespace. Every page carries `rel="describedby"` pointing at its namespace file, or at the root file outside the reference. - Each page keeps its own namespace's tree in the sidebar, and every other namespace shows one collapsed Overview link. Page HTML is 33% to 47% smaller on the four pages measured, and previous and next links are unchanged. - `deploy-smoke.mjs` checks the crawl rows after each deploy. ## Share cards and tags - Every share card shows the Earth, with its text inside the centre square that link-preview apps crop to. Cards stay under 300 KB. No card text is cut with an ellipsis; a title that does not fit fails the build. - Share tags: `og:locale` is `en_US`, `og:image:type` is set, `og:image:alt` and `twitter:image:alt` describe the card, and both image URLs end in `?v=<hash of the PNG>` so a redrawn card is a new URL. - A test on the built site checks every indexable page for exactly one of each tag, equal image URLs and a hash that matches the PNG. - Upload-ready copies of the cards are in `apps/dox/assets/share/`. ## Changelog pages - The changelog is one page per release line (`/changelog/1-21/`) plus an index, so no page nears 1 MB. Apple's Messages preview reads only the first 1 MB of a page, and the single page was 1,546,542 bytes. The largest page is now 729,975 bytes, and a build test fails on any page over 1,048,576 bytes. ## Root site card (other repo) The landing page `northguild.dev/` is a separate site. Its search data and card are made in `northguild/northguild.dev`, and both PRs are merged: - northguild/northguild.dev#21: sitemap, logo and Organization data. - northguild/northguild.dev#22: a card that survives a square crop, under 300 KB, with a versioned image URL. ## Globe, LCP and INP - The home globe starts when the page is idle and sets up in slices that yield to the main thread, so no task runs long. - Every globe pauses while off screen, while the tab is hidden, and while the search dialog or the mobile menu covers it. - Where the globe falls back to canvas 2D, it draws in a module Web Worker on an `OffscreenCanvas`. Input no longer waits for a globe frame. A probe compares text rasterisation on both paths first; if they differ, or the worker fails, the main-thread renderer takes over. The look is unchanged. - The hero clock loads `@northguild/gmt` by dynamic import beside the star list, which keeps the Temporal polyfill off the first-paint path. - The clock list measures its rows in one pass after writing them. - `apps/dox/scripts/web-vitals.mjs` measures LCP, CLS, TBT and INP by hand. Local lab numbers for the home page on mobile, before then after: TBT 464 ms to 149 ms; LCP 3.0 s (varying between runs) to 2.26 s; INP at 4x CPU throttling 256 ms to 96 ms with WebGPU, and 392 ms to 96 ms with canvas 2D. Guide and reference pages were already good. ## Owner steps From `context/domination/issues/CORE-86/search-and-crawlers.md` (runbook §8). - [x] Rich Results Test on `https://northguild.dev/` (northguild/northguild.dev#21): Organization, 0 errors, 0 warnings. - [ ] **O1** Search Console: submit both sitemaps and record the Pages report. - [ ] **O2** Search Console URL Inspection on `/gmt/` and two reference pages. - [ ] **O3** Bing Webmaster Tools: import from Search Console, then submit the sitemaps. - [ ] **O4** AI Crawl Control: record the 30-day request counts per crawler. - [ ] **O5** Crawler Hints: turn it on. Turn it off if Bing lists no IndexNow URLs within a week. ## Open checks after deploy These run against the live site, so they stay open. The list is also in `context/dox/built.md`. - [ ] Facebook Sharing Debugger, LinkedIn Post Inspector, X, Slack, Discord, WhatsApp: the card shows for `/gmt/`, a guide, a reference page and `/gmt/changelog/`; WhatsApp shows the whole title in a square crop. - [ ] iMessage: the rich preview shows for the same URLs, including a changelog line page. - [ ] The same platform checks for `https://northguild.dev/`. - [ ] `node apps/dox/scripts/deploy-smoke.mjs` passes against `https://northguild.dev`. - [ ] Rich Results Test and validator.schema.org read the Organization data on `https://northguild.dev/`. - [ ] `node scripts/web-vitals.mjs --live https://northguild.dev` with `PSI_API_KEY` set records PageSpeed Insights and CrUX numbers. ## Baseline Search Console, Bing and AI Crawl Control numbers from before deploy: _To be filled in by the owner._ ## Validation - Each slice was checked by a tester against its definition of done: - Search, crawl and `llms.txt`: the Dox Vitest suite, every built-site test on a fresh build, `astro check`, lint, a local Wrangler run of `deploy-smoke.mjs`, and a whole-site HTML comparison against `main`'s build. - Lean sidebar: the browser and keyboard checks, and the HTML sizes listed above. - Share cards and tags: card unit tests (text inside the square, contrast at least 4.5:1, no ellipsis) and `share-preview.test.ts` on a fresh build. - Changelog pages: the size test on a fresh build. - Globe: pixel comparison of the worker against the main-thread renderer, and the pause rules, in Chromium. Interior pixels differ by 1 to 14 levels where the ocean pattern is filled, and the clock card can show one frame before the globe when it mounts. Both are accepted. - Every test that reads the built site now runs in CI, found by rule (`apps/dox/scripts/dist-tests.mjs`). All 11 files pass on a fresh build. - CI on 9a3fee6: every job passed, including the Dox gates. The review fixes are in d516fc3. - Local Lighthouse, mobile, home page: performance 78 to 84 on `main`, 93 to 95 here. - `pnpm deps:sync`: no change to any `Blocked by` cell. Not verified: - `verdict validate` has not run locally: the scratch copy it would run in is not a git checkout. CI runs the same build, lint and test steps. - The globe worker has not run in real Firefox or Safari. Firefox would not start on the test machine.
The share card for
northguild.dev/is redrawn so it still reads when an app crops it to a square, and its URL now changes when the image does.What changed
scripts/build-og-card.mjsdraws it: the aurora sky, the shield above the Michroma wordmark, and "Open-source tools for developers." All the text and the shield sit inside the centre square (x 285–915), so a square crop keeps them. The panel has the theme's bevelled corners. Text contrast is at least 4.5:1.og.pngis 145 KB, down from 538 KB. WhatsApp shows no preview for images over 300 KB.og:imageandtwitter:imageend in?v=plus the first 12 hex characters of the PNG's SHA-256, read at build time. Facebook caches an image by URL, so a redrawn card is now a new URL.og:localeisen_US, the Open Graph form.apps/site/assets/share/holds the card and the old one, with a README.context/share-card.mdsays how to redraw it.https://northguild.dev/worktree/sitemap-index.xml. Crawlers readrobots.txtonly at the host root.The script runs by hand, not in the build, and gives the same bytes every run.
Validation
pnpm lint,pnpm format:check,pnpm checkandpnpm buildpass.index.htmlcarriesog.png?v=080dc75a492b, which matches the file's hash.Related: northguild/gmt#478 (the same work for the GMT docs), northguild/worktree#286 and northguild/worktree#287.