Breadcrumbs SEO microdata includes invalid values for IDs if no href

[fnune]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

If a breadcrumb item (such as a category item in the sidebar) has no link (and thus no href) the generated SEO microdata is invalid. Since the generator is designed to pick an href and use it as the id, it looks like if there's no href to take it default to whatever text is visible inside the element.

So, if you have, e.g. a sidebar with nested items:

Then the generated breadcrumbs have no links associated to them. The generator takes, in this case "MCU Guides" as its ID, which is apparently invalid:

In these cases, I think it would be appropriate to not add an ID property at all.

Reproducible demo

No response

Steps to reproduce

1. Add a nested sidebar to Docusaurus:

// E.g. in sidebar.js
module.exports = {
    docs: {
        "Some Category": {
            type: "category",
            label: "Some Label",
            items: [
                "some-category/actual-docs"
            ]
        }
    }
};

2. Run the Google rich results validator on the resulting page: https://search.google.com/test/rich-results

Confirm that the ID of the SEO microdata is Some Category, which is invalid.

Expected behavior

No ID gets added in the generated SEO microdata for breadcrumbs without an href.

Actual behavior

An invalid ID gets added, using the text value from the category breadcrumb, because there's no href to take from.

Your environment

• Public source code: https://github.com/memfault/memfault-docs/blob/main/sidebars.js
• Public site URL: https://docs.memfault.com/docs/mcu/event-serialization-overview/
• Docusaurus version used: 2.0.0-beta.18

Self-service

• I'd be willing to fix this bug myself.

[Josh-Cena]

Hi, we're aware of this issue. What do you propose to solve this (because we didn't add id but Google insists to infer it)? I'm pretty out of ideas, and I'm tempted to say this is wontfix, that if you expect the SEO metadata to be fully valid, you'd better add an href (which is what you are supposed to do for breadcrumbs anyways)

[fnune]

Ultimately I believe there's a mismatch between Docusaurus' model of breadcrumbs and Google's expectation. It seems like in the eyes of Google a breadcrumb should only exist if it links to something*. However this isn't (please correct me if I'm wrong) the Docusaurus model: for Docusaurus, a category linking to nothing is a valid breadcrumb.

I have (AFAIK) no way to control Docusaurus' breadcrumb generation, so I can't really add an href to my category breadcrumbs. This leaves me with only one practical solution: to remove the breadcrumbs altogether (which I think I can do by configuring docusaurus-plugin-content-docs).

* My personal view: a breadcrumb without a link isn't really a breadcrumb and shouldn't be added to the page. Each breadcrumb is meant to represent a page the user has visited to get to their current page. The user never visited a category page, so there should be no item for that. This would also solve the microdata issue.

[fnune]

Alternatively I could add an actual page for each category, that just links to items in the category. But the issue still stands that the breadcrumbs generated by Docusaurus don't represent clickable pages in all cases (and IMO they should).

[fnune]

Just linking up issues and PRs:

• feat: add SEO microdata for doc breadcrumbs #6697
• Automatically generated breadcrumb markup #7135

[Josh-Cena]

I have (AFAIK) no way to control Docusaurus' breadcrumb generation,

@fnune You can. The breadcrumbs are generated from the sidebar structure, so as long as each sidebar category has an index page, the breadcrumb will also have an id. Would you be happy enough if we simply add a notice that if you care about SEO, you should add an index page for each category?

Note that the Google console message is only a warning, and I believe SEO won't be undermined by this.

Again, I'm fully aware (all the way back when I sent #6697, I even noted in the PR description), I do believe this is terrible, but I don't know of a way to fix this. If you do, please kindly inform me. Otherwise, this issue is basically unactionable.

Update: this might be possible if we allow custom breadcrumb target links. See #6953

[fnune]

I think the warning "Add an index page for each category" sounds like a good idea. It's not only a potential SEO problem, it's also a UX issue because the breadcrumb that's generated isn't clickable.

I will follow your suggestion of adding index pages to category entries.

On another note, do you think I should file a different issue for this?

My personal view: a breadcrumb without a link isn't really a breadcrumb and shouldn't be added to the page. Each breadcrumb is meant to represent a page the user has visited to get to their current page. The user never visited a category page, so there should be no item for that. This would also solve the microdata issue.

E.g. "Generate no breadcrumb for category sidebar entries without a page".

[Josh-Cena]

That sounds like a viable solution as well. Users should be able to efficiently filter out all breadcrumbs without links because the UX could be potentially confusing.

Again, we could either (a) try to figure out a better heuristic so that all items have href or (b) ask users to explicitly provide an href if there's no category link, once we have #6953

[fnune]

Defaulting to link: { type: 'generated-index' } sounds reasonable but it could be considered a breaking change. Users will need to add good-looking descriptions to all their pages so that the generated indexes look good.

[fnune]

Defaulting to link: { type: 'generated-index' } sounds reasonable but it could be considered a breaking change. Users will need to add good-looking descriptions to all their pages so that the generated indexes look good.

A problem with this would be that the shorthand syntax encourages sidebar items that are not really links and potentially don't need to be. E.g. https://docusaurus.io/docs/sidebar/items#using-shorthands

So I think:

(a) try to figure out a better heuristic so that all items have href or (b) ask users to explicitly provide an href if there's no category link, once we have #6953

(a) is difficult (can't always generate a proper link), but (b) might be OK as long as there's e.g. a build error?

[Josh-Cena]

No, not defaulting category indexes, because that doesn't make much sense. But defaulting breadcrumb links is something we can do (i.e. even if there's no category link, we can find a link, like the first doc). In fact, we already have such algorithm: if JS is disabled, you can still navigate through the categories, because each category will always have a link that's clickable, just that it may be removed after React hydration.

[fnune]

No, not defaulting category indexes, because that doesn't make much sense.

You're right, thanks for the nudge. That pushed me to amend my own PR on my docs site.

But defaulting breadcrumb links is something we can do (i.e. even if there's no category link, we can find a link, like the first doc).

Sounds reasonable. That would also be a solution to this issue.