Generate Breadcrums as Google Structured Data

[Olivier Beltrami]

Hi Tim,

I am trying to implement breadcrumbs in the structured format that Google expects to display breadcrumbs in search results (https://developers.google.com/search/do ... breadcrumb).

Looking at the generated HTM files, I found the location of the breadcrumbs, and parsing the various parts of the H&M breadcrumbs HTML into the JSON format expected by Google seems relatively straightforward.

But maybe there is an easier way than writing a program to parse each of my project's HTM file, using the breadcrumb info already in my project ? That is to say, where the <p class="crumbs" id="idnav"> is generated, the very similar JSON could be generated.

Very best regards,

Olivier

[Tim Green]

Hi Olivier,

I'm not sure whether converting the breadcrumbs in the output would be a good idea. All the formatting in the CSS and in some skins a lot of the scripting depends on the current output as generated by Help+Manual, so changing the code would definitely break things, in some cases in a big way. For example, the breadcrumbs in the V3 skins are entirely dynamic, and changing anything there would stop everything in its tracks.

However, the Google breadcrumb specifications are definitely interesting and we will look into the possibility of implementing them in the future.

[Olivier Beltrami]

Hi Tim,

I would not modify the actual breadcrumbs, I would just parse them to generate JSON, similar to the example below, that I would add at the top of the HTM file.
Could that cause any problems ?

Very best regards,

Olivier

Code: Select all

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [{
    "@type": "ListItem",
    "position": 1,
    "name": "Books",
    "item": "https://example.com/books"
  },{
    "@type": "ListItem",
    "position": 2,
    "name": "Authors",
    "item": "https://example.com/books/authors"
  },{
    "@type": "ListItem",
    "position": 3,
    "name": "Ann Leckie",
    "item": "https://example.com/books/authors/annleckie"
  },{
    "@type": "ListItem",
    "position": 4,
    "name": "Ancillary Justice",
    "item": "https://example.com/books/authors/ancillaryjustice"
  }]
}
</script>

[Tim Green]

Hi Olivier,

Yes, I'm just getting into the specifications now myself and I now understand how this works. I see a problem, however: As far as I can see, Google assumes that breadcrumbs reflect a physical directory structure on the server, which does not exist in WebHelp. All the topic files are in a single folder and the TOC structure of WebHelp is entirely virtual, defined by the list structure of the TOC, which doesn't even exist as an HTML file if you are using V3 WebHelp.

This means that entries like these in your example:

Code: Select all

"item": "https://example.com/books/authors"
..
"item": "https://example.com/books/authors/annleckie"
..
"item": "https://example.com/books/authors/ancillaryjustice"

would be incorrect for topics in a single WebHelp system, because the "folders" referenced would not exist. They only exist in the virtual structure of the TOC tree. If Google or another search engine tried to parse the JSON and correlate it with the actual directory structure it would throw an error and possibly either downgrade your site or, worst case, blacklist you for attempting tricky SEO.

It's early days yet, but so far I have not been able to find a way to mark up virtual structures like this in JSON-LD and I have a suspicion that it's not a case that is covered by this specification.

[Olivier Beltrami]

Hi Tim,

I think the example I gave is misleading.

The individual items are meant to be URLs (ie. .htm files). I'm not sure why that example shows folders (probably assumes index.htm in each folder?).

From what I read, the idea of the Google breadcrumbs is exactly to provide hierarchical navigation, where none exists physically (as is the case in the H&M webhelp), or when the physical folder structure does not match the way humans would think. So this is meant to be based on one's conceptual hierarchy, rather than the actual folder structure.

Google provides an online tester. I'll run a quick test and let you know what happens.

Very best regards,

Olivier

[Tim Green]

From what I read, the idea of the Google breadcrumbs is exactly to provide hierarchical navigation, where none exists physically (as is the case in the H&M webhelp), or when the physical folder structure does not match the way humans would think. So this is meant to be based on one's conceptual hierarchy, rather than the actual folder structure.

As far as I can see, that is not the case. Google would never suggest URLs that don't exist, and all the examples I have see so far do reflect a physical URL structure. For example, all the HTML examples look basically like this:

Code: Select all

<ol>
  <li>
    <a href="http://www.example.com/books">Books</a>
  </li>
  <li>
    <a href="http://www.example.com/sciencefiction">Science Fiction</a>
  </li>
  <li>
    <a href="http://www.example.com/books/sciencefiction/awardwinners">Award Winners</a>
  </li>
<ol>

Those are physical URLs. Nothing like that exists in WebHelp, due to the virtual TOC structure. In a WebHelp site, the HTML would like like this, which would be meaningless in Terms of Google breadcrumbs:

Code: Select all

<ol>
  <li>
    <a href="http://www.example.com/webhelp">Books</a>
  </li>
  <li>
    <a href="http://www.example.com/webhelp">Science Fiction</a>
  </li>
  <li>
    <a href="http://www.example.com/webhelp">Award Winners</a>
  </li>
<ol>

Or it would look like this, which would be meaningful in a way, but would not be allowed because the markup is not supposed to show individual files in the hierarchy:

Code: Select all

<ol>
  <li>
    <a href="http://www.example.com/webhelp/books.html">Books</a>
  </li>
  <li>
    <a href="http://www.example.com/webhelp/sciencefiction.html">Science Fiction</a>
  </li>
  <li>
    <a href="http://www.example.com/webhelp/awardwinners.html">Award Winners</a>
  </li>
<ol>

[Olivier Beltrami]

Hi Tim,

I patched a file and placed it into the Google tester, and it seems happy.

Link to the Google online tester https://search.google.com/structured-da ... Ftoday.htm.

Results in Google search, showing the breadcrumb https://www.google.com/search?rlz=1C1RU ... dtZanfzXdk.

Am I missing some subtlety ?

Very best regards,

Olivier

[Tim Green]

Hi Olivier,

That's interesting -- so you can include specific files and not just folders, thus creating a virtual breadcrumb list. The examples on Google's Breadcrumb page only showed folders, which indicated to me that you really needed a folder structure. That changes things, of course. I'd be very grateful if you could report back again after a while on how it has been going for you.

[Olivier Beltrami]

Hello again,

Interestingly enough, it seems that Google actually uses the breadcrumbs generated by H&M as its search result title, without the need for me to do anything (see below). Interesting.

Very best regards,

Olivier

[Tim Green]

Hey Olivier,

This is very cool! We are definitely looking into it.

[Olivier Beltrami]

My first hint that this was possible is an example I saw in a tutorial about tickets for Amy Schumer. As you can see below, the breadcrumbs and the actual position of the target page are unrelated.