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.
When a sidebar
section:has no explicithref, breadcrumb rendering falls back to using the first child'shref. Depending on what that first child is, this produces two different surprising results:section:without anhref, the fallback resolves toundefinedand 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:
On
html-basics.html, the breadcrumb renders as:The fallback logic:
quarto-cli/src/project/types/website/website-shared.ts
Lines 358 to 364 in 3e11b83
We could discuss whether the right behavior is:
href— render as plain text so behavior is consistent and authors are explicit when they want a link.href:on sections.Reported in the docs site context as #14402.