Skip to content

Website breadcrumbs are inconsistent for sidebar sections without explicit href #14454

@cderv

Description

@cderv

When a sidebar section: has no explicit href, breadcrumb rendering falls back to using the first child's href. Depending on what that first child is, this produces two different surprising results:

  • If the first child is a leaf page, the section's breadcrumb links to that page — clicking the section header takes you to one of its children rather than to a section landing.
  • If the first child is itself a section: without an href, the fallback resolves to undefined and the breadcrumb has no link at all.

Same fallback rule, two visibly different outcomes from the user's perspective.

Example sidebar — both inconsistencies on a single page:

- section: "Documents"            # no href → no link in breadcrumb
  contents:
    - section: "HTML"             # no href, but first child is a page → links to first page
      contents:
        - docs/output-formats/html-basics.qmd
        - docs/output-formats/html-code.qmd

On html-basics.html, the breadcrumb renders as:

<li class="breadcrumb-item">Documents</li>
<li class="breadcrumb-item"><a href=".../html-basics.html">HTML</a></li>

The fallback logic:

const breadCrumbItem = { ...item };
if (
!breadCrumbItem.href && breadCrumbItem.contents &&
breadCrumbItem.contents.length > 0
) {
breadCrumbItem.href = breadCrumbItem.contents[0].href;
}

We could discuss whether the right behavior is:

  • Don't auto-link section headers without an explicit href — render as plain text so behavior is consistent and authors are explicit when they want a link.
  • Recursively walk to the first leaf descendant — closes the "no link" gap but doesn't fix the misleading-link case.
  • Keep current behavior and document it more clearly so users know to add href: on sections.

Reported in the docs site context as #14402.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestwebsitesIssues creating websites

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions