Wordpress-seo: HowTo block structured data quick fixes

[jono-alderson]

Our HowTo blocks are inconsistent with Google's guidelines, and, throw errors/warnings in Search Console. We should resolve these as a matter of urgency.

Structural changes

• [x] The top-level HowTo block should have an ID property (e.g., https://www.example.com/page/howto-123)

• [x] The HowTo block should have a mainEntityOfPage attribute, referencing the ID of the Article (or, the WebPage when there's no Article present).

• [x] Each step object must have a URL, which should match the ID/fragment of the step (https://www.example.com/page/#step-id).

• [x] Replace all current HowToSections keys with HowToStep.

• [x] ImageObject output should be consistent with our approach in other areas; i.e., height/width/caption/id, etc.

• [x] If a step has images, add them to the HowToStep node (_not_ the HowToDirection node).

Handling descriptions

• [x] If a step has a title and description:

  • [x] Set the step title as a name property.

  • [x] Output the description as a HowToDirection, in an itemListElement array (note: these are currently incorrectly set to HowToStep).

  • [ ] If a description contains multiple paragraphs (see https://nimb.ws/1NsIdW), then these should each be output as a distinct HowToDirection:

  E.g:

  "step": [{
  "@type": "HowToStep",
  "name": "The name of the step",
  "url": "https://example.com/kitchen#step1",
  "itemListElement": [{
    "@type": "HowToDirection",
    "text": "The step description."
  }]
  }]
  

  Or (multi-paragraph descriptions):

  "step": [{
  "@type": "HowToStep",
  "name": "The name of the step",
  "url": "https://example.com/kitchen#step1",
  "itemListElement": [{
    "@type": "HowToDirection",
    "text": "The first paragrah in the step description."
  },{
    "@type": "HowToDirection",
    "text": "The second paragrah in the step description."
  }]
  }]
  
  




• [x] If a step lacks a description and a title, but it does contain an image:

  • [x] Do _not_ output an itemListElement array

  • [x] Do not output a name property on the step, but do output an image property and populate it with the image schema output, and a text property with an empty string.

"step": [{
  "@type": "HowToStep",
  "text": "",
  "url": "https://example.com/kitchen#step1",
  "image": { "@id" : "http://www.example.com/#/schema/image/1234" }
}]

• [x] If a step lacks either a description or a title:

  • [x] Do _not_ output an itemListElement array

  • [x] Change the name property on the step to text, and populate it with the text content of whichever element is present.

  E.g.,

  "step": [{
  "@type": "HowToStep",
  "text": "Eat the cake",
  "url": "https://example.com/kitchen#step1"
  }]
  
  



• [x] If a step is empty (no description, no title), do not output it.

Example JSON output

{
    "@context": "https://schema.org",
    "@graph": [
    {
        "@type": "Organization",
        "@id": "http://testsite.local/#organization",
        "name": "Acne inc",
        "url": "http://testsite.local/",
        "sameAs": [],
        "logo":
        {
            "@type": "ImageObject",
            "@id": "http://testsite.local/#logo",
            "url": "http://testsite.local/wp-content/uploads/woocommerce-placeholder.png",
            "width": 1200,
            "height": 1200,
            "caption": "Acne inc"
        },
        "image":
        {
            "@id": "http://testsite.local/#logo"
        }
    },
    {
        "@type": "WebSite",
        "@id": "http://testsite.local/#website",
        "url": "http://testsite.local/",
        "name": "testsite",
        "publisher":
        {
            "@id": "http://testsite.local/#organization"
        },
        "potentialAction":
        {
            "@type": "SearchAction",
            "target": "http://testsite.local/?s={search_term_string}",
            "query-input": "required name=search_term_string"
        }
    },
    {
        "@type": "FAQPage",
        "@id": "http://testsite.local/faq-test/#webpage",
        "url": "http://testsite.local/faq-test/",
        "inLanguage": "en-US",
        "name": "FAQ test - testsite",
        "isPartOf":
        {
            "@id": "http://testsite.local/#website"
        },
        "datePublished": "2019-05-21T10:25:14+00:00",
        "dateModified": "2019-05-21T10:25:14+00:00",
        "breadcrumb":
        {
            "@id": "http://testsite.local/faq-test/#breadcrumb"
        }
    },
    {
        "@type": "BreadcrumbList",
        "@id": "http://testsite.local/faq-test/#breadcrumb",
        "itemListElement": [
        {
            "@type": "ListItem",
            "position": 1,
            "item":
            {
                "@type": "WebPage",
                "@id": "http://testsite.local/",
                "url": "http://testsite.local/",
                "name": "Home"
            }
        },
        {
            "@type": "ListItem",
            "position": 2,
            "item":
            {
                "@type": "WebPage",
                "@id": "http://testsite.local/faq-test/",
                "url": "http://testsite.local/faq-test/",
                "name": "FAQ test"
            }
        }]
    },
    {
        "@type": "Article",
        "@id": "http://testsite.local/faq-test/#article",
        "isPartOf":
        {
            "@id": "http://testsite.local/faq-test/#webpage"
        },
        "author":
        {
            "@id": "http://testsite.local/author/admin/#author",
            "name": "admin"
        },
        "publisher":
        {
            "@id": "http://testsite.local/#organization"
        },
        "headline": "FAQ test",
        "datePublished": "2019-05-21T10:25:14+00:00",
        "dateModified": "2019-05-21T10:25:14+00:00",
        "commentCount": 0,
        "mainEntityOfPage": "http://testsite.local/faq-test/#webpage",
        "articleSection": ""
    },
    {
        "@type": "Person",
        "@id": "http://testsite.local/author/admin/#author",
        "name": "admin",
        "image":
        {
            "@type": "ImageObject",
            "@id": "http://testsite.local/#personlogo",
            "url": "http://0.gravatar.com/avatar/c2b06ae950033b392998ada50767b50e?s=96&d=mm&r=g",
            "caption": "admin"
        },
        "description": "I like cake",
        "sameAs": [
            "https://twitter.com/twitterurl"
        ]
    },
    {
        "@type": "HowTo",
        "@id": "http://testsite.local/howto-test/#howto-1",
        "name": "HowTo Test",
        "totalTime": "P2DT0H0M",
        "mainEntityOfPage":
        {
            "@id": "http://testsite.local/faq-test/#article"
        },
        "description": "This is a description",
        "step": [
        {
            "@type": "HowToStep",
            "name": "The name of the step",
            "url": "https://example.com/kitchen#step1",
            "image":
            {
                "@type": "ImageObject",
                "@id": "http://testsite.local/#howto-image-1-1",
                "url": "http://testsite.local/wp-content/uploads/cake-placeholder.png",
                "width": 1200,
                "height": 1200,
                "caption": "Cake"
            },
            "itemListElement": [
            {
                "@type": "HowToDirection",
                "text": "The step description."
            }]
        },
        {
            "@type": "HowToStep",
            "name": "The name of the step",
            "url": "https://example.com/kitchen#step1",
            "itemListElement": [
            {
                "@type": "HowToDirection",
                "text": "The first paragrah in the step description."
            },
            {
                "@type": "HowToDirection",
                "text": "The second paragrah in the step description."
            }]
        },
        {
            "@type": "HowToStep",
            "text": "Eat the cake",
            "url": "https://example.com/kitchen#step1",
            "image": [
            {
                "@type": "ImageObject",
                "@id": "http://testsite.local/#howto-image-1-2",
                "url": "http://testsite.local/wp-content/uploads/cake-placeholder-2.png",
                "width": 1200,
                "height": 1200,
                "caption": "Cake 2"
            },
            {
                "@type": "ImageObject",
                "@id": "http://testsite.local/#howto-image-1-3",
                "url": "http://testsite.local/wp-content/uploads/cake-placeholder-3.png",
                "width": 1200,
                "height": 1200,
                "caption": "Cake 3"
            }]
        }]
    }]
}

[jackjwilliams]

Will this fix be scheduled into a patch release (near term) or minor / major release (longer term)?

[jono-alderson]

Hey Jack, this is fresh off the press, so it hasn't had a chance to go through our prioritisation processes yet.

However... we know that this one is important for a lot of people, and, it shouldn't be nightmarishly complex to make these changes.

I'm hoping that we can turn this around pretty quickly!

[fahimanwer]

Can you guys please tell us the time after which the issue will be solved.

[Djennez]

We don't have an exact date, but the issue is on our radar.

[jackjwilliams]

I'm holding off from creating content until this gets fixed. If I create how to blocks, will I have to re-do any of them? Or will the fix be seamless? I'm guessing the data is still the same (step names, descriptions), it's just how you render the json-ld aye?

[jono-alderson]

It shooouuuuld only be the JSON which changes. :)

[jackjwilliams]

Spoken like a true developer 😆

[jono-alderson]

Added sample JSON output; cc @IreneStr

[jono-alderson]

Added images to the example JSON.

[jdevalk]

The checked boxes reflect what #13027 does. Note that "If a description contains multiple paragraphs" isn't checked, simply because the current block doesn't allow for multiple paragraphs.

[jackjwilliams]

What ever happened with this? I saw a PR started, but then no one finished it.

[nigelhooijmans]

When will this update be live? It's really affecting SEO, my Search Console gives the same errors every time I create the How-To block:

[Xyfi]

@jackjwilliams @nigelhooijmans This issue is currently in active development.

[jackjwilliams]

I noticed that the first PR got merged, but the second one did not. I saw a release dropped today, did it include the first PR's fixes? The article did not mention it.

[shaneapen]

Do I need to update my content to fix this issue or will a patch solve this?

[Djennez]

The release which would contain these changes was moved from 11.5 to 11.6. That should be in two weeks.

[fahimanwer]

I am still facing the errors. Any update on this?

[Djennez]

If you're on 11.6 and are still facing errors generated by our plugin, please check if the same issue exists and if not, create an issue following the Bug report guidelines.

[saeedashifahmed]

After using the Yoast HowTo block in Gutenberg, I'm getting error mail on every post.

This was the mail I got from Google:

How-to issues detected on https://droidfeats.com/

To the owner of https://droidfeats.com/:

Search Console has identified that your site is affected by 3 How-to issues:

Top Warnings

Warnings are suggestions for improvement. Some warnings can enhance your appearance on Search; some might become errors in the future. The following warnings were found on your site:

Missing field 'supply'

Either 'image' or 'video' should be specified

Missing field 'tool'

We recommend that you fix these issues when possible to enable the best experience and coverage in Google Search.

Please help.

[markllego]

This bug still exists in the latest release. Please fix it. Thank you.

[jdevalk]

@markllego unfortunately, it's not an easy fix. Google is reporting an issue that should at _best_ be a suggestion. This is not a required field, your HowTo will show in search results just fine.