Skip to content

feat(seo): inject brand-level Organization JSON-LD with sameAs linking docs to the Celo entity - #2285

Open
GigaHierz wants to merge 1 commit into
mainfrom
GigaHierz/2283-org-jsonld
Open

feat(seo): inject brand-level Organization JSON-LD with sameAs linking docs to the Celo entity#2285
GigaHierz wants to merge 1 commit into
mainfrom
GigaHierz/2283-org-jsonld

Conversation

@GigaHierz

Copy link
Copy Markdown
Contributor

The hole, and the fix

Verified live today: Mintlify auto-injects an Organization schema named "Celo Docs" with no sameAs, plus a WebSite node crediting Mintlify as creator — the docs are disconnected from the Celo brand entity that search and AI engines resolve.

Adds seo-schema.js (Mintlify loads any content-directory .js on every page, no wiring needed) injecting one JSON-LD @graph: an Organization Celo (https://celo.org/#organization) with a sameAs array (GitHub org, X, YouTube, Discord, Forum, CoinGecko, DefiLlama, L2BEAT), and a WebSite node for docs.celo.org whose publisher points at that Organization — the docs→brand linkage the entity graph was missing.

What this does NOT do / residual risk

  • Client-side injection: the script runs after load. Google and DOM-rendering crawlers process it; plain-fetch crawlers see only Mintlify's static blocks. Static head injection is not available on the current plan — recorded in the file header.
  • Does not touch celo.org's own missing JSON-LD (Framer; tracked outside this repo) and cannot rename Mintlify's auto-generated "Celo Docs" nodes.
  • Duplicate-node risk is low: the injected @ids (celo.org/#organization, docs.celo.org/#celo-docs) differ from Mintlify's (docs.celo.org/#organization, docs.celo.org#website).

Judgement calls

  • sameAs list = the docs.json footer socials + the three data aggregators the entity graph needs (CoinGecko, DefiLlama, L2BEAT). Adding/removing an entry is a one-line change.
  • Logo reuses the docs logo asset; swap to a brand asset URL if marketing prefers.

Issues

Refs #2283 — closes the script box; the "verified on the preview deployment" box stays open until the Mintlify preview for this PR is up (checkbox below).

Stacking / conflicts

Branched off main, independent — new file only.

Verification evidence

# live, before this change:
$ curl -sL https://docs.celo.org/ | grep ld+json   # Organization name "Celo Docs", no sameAs; WebSite creator = Mintlify
# this branch:
$ node -e "…"    # script parses; the JSON-LD object serializes cleanly
$ mint broken-links   # on 8b7a63ef
success no broken links found

Every sameAs URL verified: five return 200 to curl; CoinGecko and DefiLlama return 403 to curl (Cloudflare bot-blocking) but their APIs confirm the slugs (api.coingecko.com/api/v3/coins/celo → id celo; api.llama.fi/v2/chains lists Celo); L2BEAT project page returns 200.

Remaining ops steps

  • Once the Mintlify preview deploys for this PR, open any page, run JSON.parse(document.querySelectorAll('script[type="application/ld+json"]')[last].text) in the console (or Google's Rich Results test) and tick this box

Checklist

  • Title is the commit message I want on main
  • Script syntax-checked; JSON-LD validated locally; all entity URLs verified
  • Known limitation (client-side injection) stated in file and above
  • No secrets in the diff

…g docs to the Celo entity

Closes #2283

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@GigaHierz
GigaHierz requested a review from a team as a code owner August 25, 2026 11:50
@GigaHierz
GigaHierz requested a review from palango August 25, 2026 11:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant