docusaurus: Breadcrumbs SEO microdata includes invalid values for IDs if no href

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

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"
            ]
        }
    }
};

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.

About this issue

Original URL
State: closed
Created 2 years ago
Comments: 17

Most upvoted comments

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.

Josh-Cena on Apr 25, 2022

If breadcrumb does not have link, we could remove the microdata?

I thought about that at the time I was implementing it, but I don’t like the idea. A breadcrumb item should be allowed without a link (at least the schema allows it, not to say it’s any good for SEO anyways)

Josh-Cena on Apr 27, 2022

I don’t know what’s a good call. The only ways we can meaningfully move this forward are:

(a) Find a way to tell Google to not generate id for items without href. The BreadcrumbList schema, I’ve checked several times, does not mandate each item to have an id, so I doubt if it’s really necessary (Google doesn’t issue an error anyways—only a warning) (b) Find a good heuristic to ensure every breadcrumb item has an href. It’s slightly more opinionated and I’m skeptical about that. © Allow you to customize breadcrumb link, i.e. #6953

But anyways, I’m going to go ahead and close this since if we agree that © is the best choice (and for the time being, you as user need to ensure that every category has a link).

Josh-Cena on Apr 26, 2022

This is fixed by https://github.com/facebook/docusaurus/pull/7179 already.

Josh-Cena on Apr 26, 2022

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 https://github.com/facebook/docusaurus/pull/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

Josh-Cena on Apr 25, 2022