Breadcrumbs not rendering properly on very long navigation paths

[wilhelmer]

Context

No response

Bug description

When using the navigation.path feature on pages with a very long, nested path, the breadcrumbs aren't rendered properly:

Possible solutions:

1. Optimize the CSS with white-space: nowrap, overflow: hidden etc.
2. Limit the path length displayed in breadcrumbs so overflow is much less likely to occur, either via an option or with a hard limit.

Related links

-

Reproduction

example.zip

Steps to reproduce

See example.zip

Browser

No response

Before submitting

• [X] I have read and followed the bug reporting guidelines.
• [X] I have attached links to the documentation, and possibly related issues and discussions.
• [X] I assure that I have removed all customizations before submitting this bug report.
• [X] I have attached a .zip file with a minimal reproduction.

[squidfunk]

Thanks for reporting. So, there's not much else that overflow scrolling that we can do here, since the space is very narrow on mobile. Overflow hidden is a bad idea though, as it's not unlikely that you're cutting mid-word.

We need to fix the wrapping, though.

[wilhelmer]

Then there's the second solution, which could look like this:

features:
  - navigation.path:
      max_length: 3

This would mean all paths below level 3 would be cut off, so all breadcrumbs on pages in Section > Subsection > Subsubsection > Subsubsubsection would be rendered as Section > Subsection > Subsubsection.

[squidfunk]

This still doesn't solve the problem on narrow screens. There might be one very very long breadcrumb that already overflows, so there's no guarantee that limiting to three breadcrumbs is sufficient. I will provide some CSS here to tune behavior, but it doesn't make sense to provide configuration options for this feature.

[wilhelmer]

Yes, that's why I wrote "so overflow is much less likely to occur". It won't help in all cases, but it will help in many real-world use cases.

Right now, there's no upper limit at all, so if you have, say, an auto-generated documentation with 20 levels, the navigation.path feature will be completely unusable. Of course, you could say that in these cases, your documentation simply sucks and the path feature is the least of your concerns. I don't know. Just thinking out loud here.

Regarding CSS: Maybe add ellipses to the last visible breadcrumb instead of horizontal scrolling?

[squidfunk]

The example you provided only includes the site output and doesn't include anything we can run to inspect, debug and fix the issue. Please provide a self-contained reproduction that we can run by using the built-in info plugin.

[squidfunk]

I'm also not able to reproduce it myself – I don't see the wrapping behavior on our docs:

[wilhelmer]

Sorry, forgot to include the sources in the ZIP. Unfortunately, I can't use the info plugin, different story.

example.zip

Also, again sorry, I didn't update to the latest version before reporting the bug. Somehow, the latest version (9.1.1-insiders-4.32.2) seems to fix the wrapping behavior. Still, I think the rendering isn't ideal with the horizontal scroll bar, I'd prefer ellipses:

[squidfunk]

The thing is, that we could do multiple things, all of those heavily opinionated and all of them solvable with CSS. Here are two ideas that you and future users can implement via additional CSS – as always, YMMV:

Limit number of navigation items

This solves https://github.com/squidfunk/mkdocs-material/issues/5156#issuecomment-1456303169:

.md-path__item:nth-child(n+4)  { 
  display: none;
}

Break items onto multiple lines

.md-path__list  {
  flex-direction: column;
  align-items: initial;
}

This could also be scoped to mobile breakpoints. As a default implementation, we will keep the overflow scrolling behavior for now, since it should cater to most installations. Thus, please customize appearance with additional CSS.

[wilhelmer]

Your "Limit number of navigation items" solution is perfect, thanks. I'll take that.

(For an equivalent of max_length: 3, it has to be nth-child(n+4). I don't want to nitpick, just for future reference.)

[squidfunk]

Thanks! I corrected the example 😉