feat: structured data for blog posts

[johnnyreilly]

Motivation

This is an implementation of adding structured data support to blog posts, as discussed here: #5321

The aim being to improve SEO of blog posts rendered with Docusaurus.

Have you read the Contributing Guidelines on pull requests?

Yes

Test Plan

It doesn't look like there's any automated tests for this area, so let me show you what my manual testing resulted in. With the change in place, blog posts have a new JSON-LD structured data section of BlogPosting type appearing in the head which contains a subset of the frontmatter metadata:

<script type="application/ld+json" data-react-helmet="true">
{
    "@context":"https://schema.org",
    "@type":"BlogPosting",
    "headline":"Announcing Docusaurus 2 Beta",
    "description":"After a lengthy alpha stage in order to ensure feature parity and quality, we are excited to officially release the first Docusaurus 2 beta.",
    "image":["/assets/images/social-card-414bbe5147ecc177bbe8d858616709c5.png"],
    "datePublished":"2021-05-12T00:00:00.000Z",
    "author":{"@type":"Person","name":"Docusaurus maintainer","url":"imageurl"}
}
</script>

This results in structure data which Google can parse - as tested using the Rich Results Test tool: https://search.google.com/test/rich-results

[netlify]

✔️ [V2]
Built without sensitive environment variables

🔨 Explore the source changes: aa5b95b

🔍 Inspect the deploy log: https://app.netlify.com/sites/docusaurus-2/deploys/6112d739f815660008ae3c68

😎 Browse the preview: https://deploy-preview-5322--docusaurus-2.netlify.app

[github-actions]

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🟢 Performance	96
🟢 Accessibility	98
🟢 Best practices	100
🟢 SEO	100
🟢 PWA	95

Lighthouse ran on https://deploy-preview-5322--docusaurus-2.netlify.app/

[johnnyreilly]

The failing test is (I think) unrelated to this PR. It looks like there's an issue with GitHub actions or yarn possibly

[slorber]

Thanks, that looks like a good start but there are 2 issues:

• I'd rather extract all that in a separate theme comp, so that users swizzling BlogPostItem have less code to maintain on their side
• This comp is used on the "list" view also (https://deploy-preview-5322--docusaurus-2.netlify.app/blog/) => I don't think multiple posts metadatas should be added on this page?

FYI I noticed rich results on my blog posts and my blog's theme has support for this, it could be a good source of inspiration?
https://github.com/narative/gatsby-theme-novela/blob/master/%40narative/gatsby-theme-novela/src/components/SEO/SEO.tsx
It looks quite different from your schema 😅

[johnnyreilly]

Oh that's cool thanks for sharing!

I'd rather extract all that in a separate theme comp, so that users swizzling BlogPostItem have less code to maintain on their side

Yup - can do

This comp is used on the "list" view also (https://deploy-preview-5322--docusaurus-2.netlify.app/blog/) => I don't think multiple posts metadatas should be added on this page?

Good shout - will look into

[johnnyreilly]

I looked at your gatsby example; it would be great to add some of these properties to the author:

        "description": "${authorsBio}",
        "sameAs": [
          "${twitter.url}",
          "${github.url}",
          "${linkedin.url}",
          "${medium.url}"
        ]

but it doesn't look like these things live in the frontmatter / docusaurus.config.js at present so I've left it be for now.

I've moved structured data out into a separate BlogPostStructuredData component as suggested. It's only used from the BlogPostPage component. Hopefully that's good?

[slorber]

LGTM, going to merge this for now.

Note I'm also adding the possibility to define per-md metadata in #5330

Yeah we don't handle such author frontmatter for now.
But the blog frontmatter validation accept unknown keys so

I think this feature should be a "good enough" one for now. If the user needs something more advanced it should be possible to:

• swizzle the BlogPostStructuredData and use some custom frontmatter if needed
• add an extra <script type="application/ld+json"> through the new per-md metadata

This use-case is even in the helmet doc: https://github.com/nfl/react-helmet

[johnnyreilly]

Fixed the missing bit.

Note I'm also adding the possibility to define per-md metadata in #5330

Yeah I like this

[slorber]

LGTM 👍

[pranay01]

@johnnyreilly is this feature enabled by default for beta.5 or we have to take some steps to configure it?

I updated my package.json to beta.5 but still not seeing rich data for my blogs

[slorber]

@pranay01 how did you test that it works or not? What's your blog URL?

Don't expect changes to happen immediately on Google, it may take time, and Google may decide to not show the structured data for some reasons.

The only thing we can do is put the data on the page, we can't tell Google what to do with it.

Please verify with https://search.google.com/test/rich-results

[johnnyreilly]

feature is enabled by default - and I echo what @slorber says

[pranay01]

My blog URL - https://signoz.io/blog/opentelemetry-vs-prometheus/
I tested on https://search.google.com/test/rich-results

I understand google may not show it in structured results, but I think it should show up here - https://search.google.com/test/rich-results

The rendered HTML doesn't have any BlogPosting metadata which should be present if this is working.

[slorber]

It's very likely that you swizzled the theme Blog post components.

You have to keep them up to date to ensure you don't miss new Docusaurus features. You can re-swizzle the comps and re-apply your modifications.

(Also take a look at #5468)

[pranay01]

oh, yes. I had swizzled few components. Any handy docs on how to re-swizzle and apply modifications?

[slorber]

oh, yes. I had swizzled few components. Any handy docs on how to re-swizzle and apply modifications?

Unfortunately, there's no easy way to do that currently, you just have to re-swizzle the comps (using the same initial command) and use git diff merge with your own modifications. I have some ideas to make this process easier but not implemented.

[slorber]

Found this comment on a Astro site:

https://stackblitz.com/github/snowpackjs/astro/tree/latest/examples/docs?file=src%2Fcomponents%2FHeadSEO.astro

<!--
  TODO: Add json+ld data, maybe https://schema.org/APIReference makes sense?
  Docs: https://developers.google.com/search/docs/advanced/structured-data/intro-structured-data
  https://www.npmjs.com/package/schema-dts seems like a great resource for implementing this.
  Even better, there's a React component that integrates with `schema-dts`: https://github.com/google/react-schemaorg
-->

interesting package https://github.com/google/react-schemaorg

[johnnyreilly]

Yay the TypeScript support! I did a talk recently on the topic and wish I'd mentioned that

https://youtu.be/zi1CHB-eVck

[dandv]

Where is the official documentation for this feature? Searching for "structured data" doesn't return anything directly relevant.

https://docusaurus.io/docs/seo#rich-search-information doesn't say much.

[slorber]

There is no particular documentation for this feature.

Docusaurus tries to do the right SEO, accessibility, perf things by default, and we keep improving over time. Documenting all this in detail would take a lot of time and wouldn't be very readable anyway. The source of truth is the code and the actual SEO results.

If you don't agree with Docusaurus SEO defaults, we are open to discussions or improvement suggestions. And you can override our defaults by using swizzle and the <Head> component.