ENH: Add breadcrumbs to article header

[choldgraf]

This is a prototype to add a breadcrumbs component to our article header. Right now the goal is to get feedback about the feature and decide if it is useful.

Major updates:

• Adds a start and end section to the article-header section. These snap to the beginning and end of the article header. The whole thing will be hidden as you scroll down, so it is just above the title. These are defined in the theme similar to our navbar with theme_article_header_start and theme_article_header_end. You can remove the template the same way you'd remove it for the other section areas.
• Adds a breadcrumbs component to the start section. This will show links to all parent pages up to home. It will only show for pages that are nested under a top-level page (so won't show for the root page and first-level pages). My rationale is that this saves screen real estate when this is redundant information with the other active menu items but happy to add it to earlier pages if people prefer.

Example

Here's what it looks like on our admonition page. Note that it wouldn't show up on the root or any of our top-level pages.

References

• If merged, closes Add breadcrumbs with links to parent pages in the article header #1137

[choldgraf]

BTW there's a good chance that I won't have time to polish this up before paternity leave, so if others think this is a good idea then feel free to make edits and changes if you wish in order to make this merge able. For now consider it a prototype to demonstrate the feature.

[12rambau]

Super nice implementation, I would need to play with it before making a real review but as a starter, it feels ok to not have it on the landing page but I would add it to the first-level one directly for consistency.

[trallard]

I wonder if adding some breadcrumb-depth setting or something like that would be best (akin to TOC-depth). So that if one has deeply nested pages like

Home > Section 1 > Section 1.1 > Section 1.1.1 > Section 1.1.1.1

This can be truncated and replaced with an ellipsis, let's say at level 3 or other like so:

Home > Section 1 > ... > Section 1.1.1.1

This would be helpful to also avoid taking over too much space, especially on narrower screens.

[trallard]

Thanks @choldgraf - I know you might not be able to finish this, but I also wanted to add a review and comments in case anyone else is up for moving this forward.

I only realised that the breadcrumbs do not include the current page, right?
I would suggest adding the current page to the end of the breadcrumbs but not styling it as a link to avoid confusion and instead label them with aria-current="page" to help with navigation for screen readers users.

[choldgraf]

OK y'all nerdsniped me and I cleaned some stuff up :-)

• The breadcrumbs now show an ellipsis when we have more than 2 parents (excluding the home page).
• They now include the page title
• The font size is a little bit smaller to avoid cluttering the top of the page too much (I used the same .em as Docusaurus, which was .8)
• I made flex-wrap: wrap so that breadcrumbs will wrap on mobile screens and take up less space.

Example of behavior as you navigate the docs. You can see I start at the home page, dig two levels deep and the breadcrumbs all show up, and when I dig a third level deep we see the ellipsis.

[trallard]

💀 apologies for the nerd sniping 💀

This looks pretty good - I know your rationale for the breadcrumb links is for them to have a behaviour close to the navbar links. But with that current styling, the links look closer to text than to links, so it might not be evident that they are interactive elements at first glance. The subtle colour change might not be enough to provide such context (so we need a non-colour cue).
Looking at other pages with breadcrumbs, these seem to have a distinct styling, such as:

1. gov.uk -> underlined text (without the regular link colour, which is blue)
   

2. MDN web docs -> the surrounding <nav> has its own styling (which makes it stand out and different to the main navbar and main content section)
   

3. Docusaurus -> an interesting one in the sense that only the current page has a different styling (corresponding to an active state)
   

4. GitHub -> breadcrumbs are styled as links except for the current page
   

[choldgraf]

I'll try and make them the color of links and see how that looks. 👍

I think that making a little dedicated style for the whole section would be cool but I don't think I have the design skills to figure that out (nor the time, i could have a baby fairly soon)

[choldgraf]

OK I made the breadcrumbs keep the same link color as our page content. I also added a bit more documentation about them. Here's how they look:

[trallard]

I think we can work with that - and then I can add any improvements needed for it to the backlog of other design + accessibility work for the theme 😉

[drammock]

Brilliant, thanks @choldgraf