[PR] feat(seo): add Article, FAQPage & BreadcrumbList structured data to Learning Center articles [apisix-website]

["moonming (via GitHub)" <gi...@apache.org>]

moonming opened a new pull request, #2058:
URL: https://github.com/apache/apisix-website/pull/2058

   ## Summary
   
   Adds **Article + FAQPage + BreadcrumbList** structured data to Learning Center articles. Previously these articles carried only the site-wide `Organization` + `WebSite` JSON-LD — no per-article schema at all — so they were ineligible for article / FAQ / breadcrumb rich results and weaker as AI-overview citation sources, even though several already contain FAQ sections in their content.
   
   This is item **P0-2** from the SEO roadmap (the highest-ROI structured-data work): one wrapper uplifts all 13 existing articles at once.
   
   ## What changed
   
   ### `website/src/theme/BlogPostPage/index.tsx` (new — thin wrapper)
   Wraps `@theme-original/BlogPostPage` and, **scoped to `/learning-center/`**, injects:
   - **Article** + **BreadcrumbList** for every article (derived from post metadata — title, description, date, permalink).
   - **FAQPage** when the article declares an `faq` array in its front matter.
   
   Other blog instances (events, articles) are rendered untouched. Publisher/logo mirror the site-wide schema (`Apache APISIX` + `logo2.svg`) and the existing `blog/` workspace `BlogPosting` pattern. URLs are absolute and use the canonical trailing-slash form.
   
   ### `faq:` front matter (2 articles)
   Added to the two articles that already have FAQ sections — `what-is-an-api-gateway` (5 Q&As) and `open-source-api-gateway-comparison` (4 Q&As). Schema answer text matches the visible on-page answers (Google's FAQ requirement).
   
   ## Verification — production (SSR) build
   
   Built the site (`yarn workspace website build`, green in ~93s) and grepped the generated HTML — this is exactly what crawlers receive:
   
   | Article | Article | BreadcrumbList | FAQPage |
   |---|---|---|---|
   | what-is-an-api-gateway | ✅ | ✅ | ✅ 5 Q&A |
   | open-source-api-gateway-comparison | ✅ | ✅ | ✅ 4 Q&A |
   | apisix-vs-kong | ✅ | ✅ | — (no `faq`) |
   | api-gateway-security | ✅ | ✅ | — (no `faq`) |
   
   Article carries headline/description/datePublished/dateModified, Organization author + publisher (with logo), and `mainEntityOfPage`. BreadcrumbList is Home → Learning Center → article with absolute URLs. Confirmed Docusaurus passes the custom `faq` front matter through (`validateFrontMatter` uses `allowUnknown: true`), so the build accepts it and the component receives it.
   
   ## SEO / GEO rationale
   - **FAQ rich results + AI citations** — the FAQ content existed but was invisible to crawlers and AI engines; marking it up makes APISIX the citable source for these high-intent questions.
   - **Article rich results** — author/date/publisher signals on every Learning Center page.
   - **BreadcrumbList** — breadcrumb SERP display + clearer site structure for crawlers.
   
   ## Test plan
   - [x] Production build green; SSR output verified per the table above
   - [x] Custom `faq` front matter parses as `{q, a}` arrays (gray-matter) and passes Docusaurus validation
   - [x] Non-FAQ articles correctly emit Article + Breadcrumb only
   - [ ] CI deploy build green
   - [ ] Post-merge: validate a sample URL in Google Rich Results Test
   
   ## Notes / follow-ups
   - Only 2 articles have FAQ sections today; adding `faq` front matter to more articles (and authoring FAQ sections) is a content follow-up — the wrapper already handles them automatically.
   - The wrapper is additive and scoped; it does not change rendered article markup.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] feat(seo): add Article, FAQPage & BreadcrumbList structured data to Learning Center articles [apisix-website]

["Yilialinn (via GitHub)" <gi...@apache.org>]

Yilialinn merged PR #2058:
URL: https://github.com/apache/apisix-website/pull/2058


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] feat(seo): add Article, FAQPage & BreadcrumbList structured data to Learning Center articles [apisix-website]

["moonming (via GitHub)" <gi...@apache.org>]

moonming commented on PR #2058:
URL: https://github.com/apache/apisix-website/pull/2058#issuecomment-4788728760

   ## Independent audit (resolved)
   
   An independent adversarial review (no shared context, isolated worktree) checked schema validity, reliability/edge cases, JSON-LD injection, scope/breaking-changes, and verification adequacy. Findings and resolution:
   
   | Sev | Finding | Resolution |
   |-----|---------|------------|
   | **MEDIUM** | FAQ #3 schema answer used an em-dash `—` while the rendered body shows literal `---` (beta.6 has no smartypants) → violates Google's FAQ answer-must-match-page rule | **Fixed** (`5736bb90b`) — front matter reverted to `---`; re-verified the SSR answer text now matches the body byte-for-byte |
   | **LOW** | `Article` had no `image` → Google "missing field image" warning | **Fixed** — fall back to the site's default social card (`static.apiseven.com/202202/apache-apisix.png`, same as the site `og:image`); every article now carries an image |
   | **LOW** | `JSON.stringify` doesn't escape `</script>`; FAQ prose could contain `<` | **Fixed** — added a `toJsonLd` helper escaping `<` → `<`; 0 parse errors in build output |
   | **MEDIUM** | No automated regression test (manual SSR-grep only) | **Deferred w/ justification** — the repo has no structured-data test harness and wiring a post-build assertion into CI is out of scope for this focused PR. Manual SSR verification is documented above; filing a follow-up to add a build-output schema assertion. |
   
   Reliability, scope, and no-duplication lenses came back clean (verified against the beta.6 plugin source): the Organization-author fallback is exercised on every article, `events`/`articles` instances hit the early return untouched, and the global `schema-org` plugin only emits `WebSite`/`Organization` so there's no duplication.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org