Proposal: migrate blog structured data back to JSON-LD

[johnnyreilly]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Description

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, and it affords more possibilities for implementing a knowledge graph in your site.

I'd like to investigate moving Docusaurus back to using JSON-LD for blog Structured Data, but with some slight differences in approach to my original approach. I've raised this issue to discuss it.

Relevant links on JSON-LD

Google recommend JSON-LD as a format:

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).

https://www.searchenginejournal.com/google-structured-data-preference/297479/

In a Webmaster Hangout, Google’s John Mueller was asked what kind of structured date Google prefers. John Mueller answered that Google prefers JSON-LD structured data.

https://yoast.com/structured-data-schema-ultimate-guide/#son

JSON-LD is the preferred method of adding structured data to your site

What I'd implement differently this time

@slorber said

I tend to prefer co-locating things, it improves composability and make sure all pages using a cmp with structured data will be well-understood by crawlers without additional work

I agree with this sentiment. In my original implementation I was rendering the JSON-LD to head tags which it turns out is completely unnecessary (and unhelpful for the reasons documented by @slorber). Consider the about page of my site:

https://johnnyreilly.com/about

This has Person Structured Data implemented in the body of the page, the structured data validator validates this

What do people think?

I'm happy to do this work, but I don't want to devote time to it if there's no hope of it landing. So I wanted to solicit thoughts here first.

Finally, it's worth noting that we advocate using JSON-LD in the SEO docs of Docusaurus:

docusaurus/website/docs/seo.mdx

Lines 36 to 49 in 6f9f8ee

	// Declare some json-ld structured data
	{
	tagName: 'script',
	attributes: {
	type: 'application/ld+json',
	},
	innerHTML: 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',
	}),
	},

Feels like it would be good to use one format of Structured Data rather than a variety; principle of least surprise etc.

Has this been requested on Canny?

No

Motivation

See description

API design

LIkely the same as the original implementation but not rendering to the Head

Have you tried building it?

Yes

Self-service

• I'd be willing to contribute this feature to Docusaurus myself.

[Josh-Cena]

It's "prefered" in the sense that it's less error-prone and easier to maintain—but if we don't need to maintain anything and there doesn't appear to be an error in the status quo, is there another good reason to migrate?

[johnnyreilly]

There's a number of good reasons to migrate:

• it aligns with the approach favoured by the SEO industry and the main search engine Google
• it aligns with other documentation on the Docusaurus website around using structured data

More significantly than the above reasons, having JSON-LD structured data support with Docusaurus (assuming a similar implementation to previously) would mean a structured data component that is swizzle-able which gives users the ability to control their structured data directly, should they choose to want it to be slightly different to the specific contents of their blog.

For instance, it would allow Docusaurus users to do more extensive knowledge graph support. JSON-LD is specifically designed for linked data, which means it's better suited for creating relationships between different pieces of data.

This is just one example.

And to be clear: I'm offering to do the work. I'm not proposing it with the expectation someone else would

[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.

[johnnyreilly]

I have really come to love swizzleability. And yes, I have decided that is a word!

[homotechsual]

I think this would be a solid change and the swizzlability alone makes it desirable.

[hrumhurum]

A big benefit of JSON-LD when compared to microdata is that JSON-LD is easier to author, but more importantly, it's a stricter format designed for machine consumption and validation. Also, JSON-LD conveniently stays aside of content, meaning that it does not intermix with it, thus not producing a big mess like microdata tends to do.

I used both formats in my practice. As the time went, Microdata turned out to be a royal pain, so I had to migrate to JSON-LD due to the aforementioned reasons. While microdata sounds like a neat idea, in practice JSON-LD is just better.

[johnnyreilly]

There seems to be general assent for this idea - I'm planning to do some work on it. Probably once I've migrated to Docusaurus v3

[johnnyreilly]

I'm starting to turn my attention to this now. All being well I'll see if I get a PR together over the holidays. Merry Christmas all! 🎄

[johnnyreilly]

I've now implemented this with #9669

[slorber]

@johnnyreilly just noticed there's a "TechArticle" schema type too 🤪

Wonder if we should have a way to specific the actual type to use between "BlogPosting" and "TechArticle" 🤷‍♂️

• https://schema.org/BlogPosting
• https://schema.org/TechArticle

Found this on @alexmacarthur blog post: https://macarthur.me/posts/structured-data-with-starlight/

[johnnyreilly]

Interesting!