SEO: add JSON-LD structured data (SoftwareSourceCode, WebSite+SearchAction, BreadcrumbList, TechArticle)

[limonte]

Problem

The site has no structured data at all — no JSON-LD, no microdata. For a library documentation site there are several schema types that Google actively uses.

Suggested additions

1. SoftwareSourceCode / SoftwareApplication on the homepage — describes the library itself (name, license MIT, repo URL, programming language, version). Feeds knowledge-panel-style understanding of "what is SweetAlert2".

{
  "@context": "https://schema.org",
  "@type": "SoftwareSourceCode",
  "name": "SweetAlert2",
  "description": "A beautiful, responsive, customizable, accessible (WAI-ARIA) replacement for JavaScript's popup boxes",
  "codeRepository": "https://github.com/sweetalert2/sweetalert2",
  "programmingLanguage": "JavaScript",
  "license": "https://opensource.org/licenses/MIT",
  "url": "https://sweetalert2.github.io/"
}

2. WebSite + SearchAction — the site already has Algolia DocSearch; declaring it enables a sitelinks search box.

3. BreadcrumbList on the 21 recipe pages — Home › Recipe Gallery › Colored Toasts. Google renders breadcrumb trails in place of the raw URL in search results. There is currently no breadcrumb markup or visible breadcrumb UI (recipe pages only have a "Back to Recipe Gallery" link).

4. TechArticle on each recipe page — headline, description, about, proficiencyLevel. Recipes are exactly what this type is for.

5. Organization — for the SweetAlert2 project, with logo and sameAs pointing at the GitHub org / npm.

6. FAQPage — only if a real FAQ section gets added; not applicable today.

Where to put it

partials/head.html can take a jsonld param the same way it takes title, with tools/generate-recipe-html.mjs emitting per-recipe BreadcrumbList + TechArticle blocks from its existing recipes array.

Validate with the Rich Results Test and validator.schema.org.

Impact

Medium — no direct ranking boost, but breadcrumbs and richer result presentation measurably improve CTR.

[limonte]

Correction before implementing this: item 2 is dead, and the rest need honest expectations set.

Item 2 (WebSite + SearchAction) — remove it

Google retired the sitelinks search box in November 2024. The markup no longer produces any rich result. Adding it would be pure maintenance cost for zero effect, so I've dropped it.

Which of the remaining types actually earn anything

I filed these as one undifferentiated list, which obscured that only one produces a Google rich result:

Item	Google rich result?
BreadcrumbList (item 3)	Yes — renders a breadcrumb trail in place of the raw URL
SoftwareSourceCode (item 1)	No. Valid schema.org, no rich result
Organization (item 5)	No standalone result; feeds logo/knowledge-graph understanding
TechArticle (item 4)	Effectively no — Article rich results are for news/blog content, not reference docs
FAQPage (item 6)	Already noted N/A; also heavily deprecated by Google in 2023

BreadcrumbList is where the value is, and it's the CTR win I claimed for the issue as a whole.

What #265 implements

• BreadcrumbList on all 21 recipe pages — the real win
• SoftwareSourceCode + nested Organization on the homepage — no rich result, but cheap, valid, and genuinely useful to non-Google consumers (LLM crawlers, and anything reading schema.org)

What I deliberately left out

• WebSite + SearchAction — retired, see above
• TechArticle — would duplicate the <title>/description already present and add per-recipe maintenance for no benefit. datePublished/dateModified would also have no honest source, same reason sitemap.xml has no <lastmod> (SEO: no canonical tags, no sitemap.xml, no robots.txt #252)
• SoftwareApplication — its rich result wants aggregateRating/offers and targets installable apps; a JS library doesn't fit, and inventing ratings would be fabrication

One caveat on breadcrumbs

Google prefers structured-data breadcrumbs to match visible on-page navigation. Recipe pages have a "← Back to Recipe Gallery" link, which is a reasonable equivalent but not a real trail. Adding a visible breadcrumb would strengthen it — worth a follow-up, and it overlaps the "no breadcrumbs" point in #256.

[limonte]

Closing: everything actionable here has shipped, and the rest was ruled out on purpose.

Shipped

Item	Where
SoftwareSourceCode + nested Organization on the homepage	#265
BreadcrumbList on all 21 recipe pages, generated from the same recipes array that drives the HTML and sitemap	#265
A visible breadcrumb trail, which Google prefers the markup to match	#272, fixed in #274

Deliberately not shipped

• WebSite + SearchAction — Google retired the sitelinks search box in November 2024. The markup produces no rich result, so it would be maintenance for nothing.
• TechArticle — Article-family rich results target news and blog content, not reference docs. It would duplicate the <title> and description already present, and datePublished / dateModified have no honest source (same reason sitemap.xml carries no <lastmod>, SEO: no canonical tags, no sitemap.xml, no robots.txt #252).
• SoftwareApplication — its rich result wants aggregateRating / offers and targets installable apps. Inventing ratings would be fabrication.
• FAQPage — no FAQ section exists, and Google heavily curtailed that result type in 2023.

Worth noting about the original issue text: I filed six schema types as one undifferentiated list, which obscured that only BreadcrumbList yields a Google rich result. The others are valid schema.org and useful to non-Google consumers, but they were never going to change how results render.

Two live validators are worth running now that this is deployed, since neither can read a local build: Rich Results Test and validator.schema.org.