refactor(theme): use JSON-LD instead of microdata for blog structured data

[johnnyreilly]

Pre-flight checklist

• I have read the Contributing Guidelines on pull requests.
• If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
• If this is a new API or substantial change: the PR has an accompanying issue (closes Proposal: migrate blog structured data back to JSON-LD #9274) and the maintainers have approved on my working plan.

Motivation

I originally contributed Structured Data support for blog posts back in 2021: #5322

@lex111 subsequently submitted a PR to migrate the approach to use microdata instead: #5355

I had reservations which I voiced at the time, but left it at that. Since then time I've had something of a baptism of fire around the world of SEO. And consequently I've been working with some excellent folk in the SEO industry to improve my own ranking. A thing that comes up repeatedly is a suggestion to use JSON-LD instead of microdata as that is what Google prefers: https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data#supported-formats

In general, Google recommends using JSON-LD for structured data if your site's setup allows it, as it's the easiest solution for website owners to implement and maintain at scale (in other words, less prone to user errors).

I raised #9274 to discuss this and received some good feedback.

I've now implemented JSON-LD support for the blog; both individual posts and the blog listing page. With this change in place, it's now possible to separately configure the Structured Data through swizzling the two new components:

• BlogListPage/StructuredData
• BlogPostPage/StructuredData

From @Josh-Cena:

Swizzability does seem desirable. I also wonder if there are cases in the wild where people swizzle blog component and inadvertently broke microdata. This sounds reasonable to me.

The default behaviour for these components is to produce JSON-LD structured data that aligns with the Schema.org and Google's Rich Results guidelines.

Let's talk for a moment about each of these components.

BlogListPage/StructuredData

This component is responsible for generating the Structured Data for the blog list page. It renders JSON-LD structured data that aligns with the https://schema.org/Blog schema. (Please note the examples at the bottom of the page which this implementation aligns with.)

BlogPostPage/StructuredData

This component is responsible for generating the Structured Data for the blog post page. It renders JSON-LD structured data that aligns with the https://schema.org/BlogPosting schema. (Please note the examples at the bottom of the page which this implementation aligns with.)

The BlogPosting schema is one of the structured data types that Google explicitly supports for Rich Results: https://developers.google.com/search/docs/appearance/structured-data/article#structured-data-type-definitions

All the Google-supported properties are included in the Structured Data generated by this component apart from dateModified which is optional. A number of other properties documented in the BlogPosting schema are included as well.

Test Plan

I will use the pull request preview on this PR to demonstrate that the Structured Data is generated as expected. I will also use the Structured Data Testing Tools to verify that the Structured Data is valid:

• https://search.google.com/test/rich-results - this tool is used to test for Rich Results; only applicable to the blog post page
• https://validator.schema.org/ - this tool is used to validate the Structured Data; applicable to both the blog list page and the blog post page

Expect screenshots to be added to this PR.

Test links

Deploy preview: https://deploy-preview-9669--docusaurus-2.netlify.app/

BlogListPage/StructuredData

If we go to the test preview of the /blog page: https://deploy-preview-9669--docusaurus-2.netlify.app/blog

We can validate with schema.org that the Blog structured data is valid: https://validator.schema.org/#url=https%3A%2F%2Fdeploy-preview-9669--docusaurus-2.netlify.app%2Fblog

BlogPostPage/StructuredData

If we go to the test preview of the /blog/releases/2.4/ page: https://deploy-preview-9669--docusaurus-2.netlify.app/blog/releases/2.4/

We can validate with schema.org that the BlogPosting structured data is valid: https://validator.schema.org/#url=https%3A%2F%2Fdeploy-preview-9669--docusaurus-2.netlify.app%2Fblog%2Freleases%2F2.4%2F

And we can also test this type with the Rich Results tool: https://search.google.com/test/rich-results

You can also see this in the Ahrefs Chrome extension: https://chromewebstore.google.com/detail/ahrefs-seo-toolbar-on-pag/hgmoccdbjhknikckedaaebbpdeebhiei?pli=1

Related issues/PRs

#9274

[netlify]

✅ [V2]

Built without sensitive environment variables

Name	Link
🔨 Latest commit	e0da5cf
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/658a901701f7a80008a486f9
😎 Deploy Preview	https://deploy-preview-9669--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[netlify]

✅ [V2]

Name	Link
🔨 Latest commit	96073e8
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/65ce26f897d19b0008565473
😎 Deploy Preview	https://deploy-preview-9669--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[github-actions]

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	PWA	Report
/	🟠 66	🟢 98	🟢 96	🟢 100	🟠 88	Report
/docs/installation	🟢 90	🟢 96	🟢 100	🟢 100	🟠 88	Report
/docs/category/getting-started	🟠 77	🟢 100	🟢 100	🟢 90	🟠 88	Report
/blog	🟠 71	🟢 100	🟢 100	🟢 90	🟠 88	Report
/blog/preparing-your-site-for-docusaurus-v3	🟠 66	🟢 96	🟢 100	🟢 100	🟠 88	Report
/blog/tags/release	🟠 70	🟢 100	🟢 100	🟠 80	🟠 88	Report
/blog/tags	🟠 77	🟢 100	🟢 100	🟢 90	🟠 88	Report

[johnnyreilly]

Hi @Josh-Cena and @slorber!

I was wondering if there were any thoughts about this PR? There's been no comments on it and so I'm not sure if you're aware it is here? I've been checking back every week or so for a while but there appears to be no activity.

It's possible you're not interested in the PR - if so would you be able to let me know and I'll close it for tidiness sake?

[Josh-Cena]

Sorry! I'm indeed aware of this. However my repo access isn't renewed so there isn't much I can do. If you've tested it yourself and it works, I'm personally happy to try it out and improve it where necessary.

[johnnyreilly]

Yeah this PR was a Christmas project for me - I think it's a really good piece of work actually! (Of course I'm biased 😀)

I think it puts the structured data story of Docusaurus in a really great place as it offers a really good default JSON-LD structured data story and freedom for users to straightforwardly control the structured data produced through the magic of swizzling. (In fact if they wanted to they could easily use the same mechanism to stop producing structured data)

If you've tested it yourself and it works, I'm personally happy to try it out and improve it where necessary

I have indeed and I'm happy to take feedback to improve it as necessary.

[slorber]

Thanks, that seems reasonable to use the solution recommended by Google 👍

Review:

• I'd like to get rid of the 2 meta attributes you added
• We can probably reduce code duplication

[johnnyreilly]

Thanks for the review @slorber - useful points, will address them soon!

[slorber]

Some additional changes requested and a few questions

If we merge this, should this be considered as a breaking change? 🤷‍♂️

[slorber]

can you explain how to reproduce that problem here?

Was the code we documented before affected by any issue?

        <script type="application/ld+json">
          {JSON.stringify({
            '@context': 'https://schema.org/',
            '@type': 'Organization',
            name: 'Meta Open Source',
            url: 'https://opensource.fb.com/',
            logo: 'https://opensource.fb.com/img/logos/Meta-Open-Source.svg',
          })}
        </script>

Can you show side-by-side examples in a repro, before/after, rendering differently in practice? And explain how it upsets parsers?

[johnnyreilly]

Was the code we documented before affected by any issue?

Yes.

So this was a curious one. The issue surfaces in the Google Search Console, and relates to the unsuccessful parsing of the inner JSON when it is directly rendered internally to the <script type="application/ld+json"> element. The Google Search Console sends a notification asking you to fix this issue:

Parsing error: Missing '}' or object member name.

This happens because by not using the dangerouslySetInnerHTML approach, the " characters in the JSON-LD are rendered as " - which is not valid JSON. So something like this:

<script type="application/ld+json">
  {
    &quot;@context&quot;: &quot;https://schema.org/&quot;,
    &quot;@type&quot;: &quot;Organization&quot;,
    &quot;name&quot;: &quot;Meta Open Source&quot;,
    &quot;url&quot;: &quot;https://opensource.fb.com/&quot;,
    &quot;logo&quot;: &quot;https://opensource.fb.com/img/logos/Meta-Open-Source.svg&quot;
  }
</script>

Rather than:

<script type="application/ld+json">
  {
    "@context": "https://schema.org/",
    "@type": "Organization",
    "name": "Meta Open Source",
    "url": "https://opensource.fb.com/",
    "logo": "https://opensource.fb.com/img/logos/Meta-Open-Source.svg"
  }
</script>

Curiously, Google will sometimes parse the " style successfully. But more often it won't (TBH I'm surprised it ever succeeds). When I migrated to the dangerouslySetInnerHTML approach instead it always parsed successfully and this fixed the issue being logged in the Google Search Console:

For reference, this is when I implemented the fix on my own site: https://github.com/johnnyreilly/blog.johnnyreilly.com/pull/664/files#diff-c2bd2d1e0092d85d7acaff15ce9223d0202ef706c2497f7500b1a24db9bc0366

[johnnyreilly]

If we merge this, should this be considered as a breaking change? 🤷‍♂️

No - I can't think of any reason why it would be

Some additional changes requested and a few questions

Cool - I've addressed these. See my responses above!

[johnnyreilly]

Hey @slorber,

It's been two weeks - just wanted to check in and see how the "amélioration" section of Docusaurus Google Search Console is looking? Does it look okay?

[slorber]

So far it doesn't seem to affect SEO much.

But I'll keep monitoring this for a few more weeks to be sure. Impressions (purple) have slightly decreased, but it could be seasonality, Google algorithm changes, or something else 🤷‍♂️

Surprisingly the number of clicks (blue) remains as high as before so maybe the search just became more relevant?

Do you observe similar behavior on your site?

---

We still have the same breadcrumbs suggestions being reported:

[johnnyreilly]

But I'll keep monitoring this for a few more weeks to be sure. Impressions (purple) have slightly decreased, but it could be seasonality, Google algorithm changes, or something else 🤷‍♂️

Surprisingly the number of clicks (blue) remains as high as before so maybe the search just became more relevant?

I suspect this is just slight variability - essentially SEO unaffected. If things change massively then it's a concern; slight variance then it's likely just fine. (SEO will always vary slightly over time and that's out of our control in the main and nothing to worry about)

We still have the same breadcrumbs suggestions being reported:

have you done anything to remedy this? I didn't spot a PR but I might have missed.

TL;DR - so far it sounds fine

[slorber]

Agree 👍 I still want to work on a few things for v3.2 so maybe we'll include this PR in v3.2 in a few weeks.

have you done anything to remedy this? I didn't spot a PR but I might have missed.

Not a high priority for me to investigate atm, I'll get back to it later so if you know how to fix the problem go ahead.

We have this being reported for docs and blog posts too. Not sure why I can't get this UI in English easily 😅

Missing "position" field (in "itemListElement")
Items with this problem are invalid. Invalid items cannot appear in the enhanced Google search results.

[johnnyreilly]

Not a high priority for me to investigate atm, I'll get back to it later so if you know how to fix the problem go ahead.

I'm pretty snowed right now, but I might see if I can take a look in a couple of weeks when things quiet down (I hope)

[slorber]

Today's SEO results:

Still less impressions, but more clicks, so maybe it's just Google targeting better the impressions 🤷‍♂️

Anyway, this doesn't destroy our SEO so it looks relatively safe to release.

[johnnyreilly]

Looks good - ship it!

[FixTheAdmin]

Great work on this @johnnyreilly. Is the change live? I don’t see it in the changelog.

[johnnyreilly]

I think it went live with 3.2

https://github.com/facebook/docusaurus/releases/tag/v3.2.0