Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ENH: Add breadcrumbs to article header #1142

Merged
merged 9 commits into from
Feb 9, 2023
Merged

Conversation

choldgraf
Copy link
Collaborator

@choldgraf choldgraf commented Jan 29, 2023

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.

chrome_IbdAteIhBK

References

@choldgraf
Copy link
Collaborator Author

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.

Copy link
Collaborator

@12rambau 12rambau left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@@ -0,0 +1,16 @@
{%- block breadcrumbs %}
{#- Only show breadcrumbs if we are nested under a top-level header #}
{# Otherwise the breadcrumbs would just be the "home" button -#}
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Collaborator

trallard commented Feb 7, 2023

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
Copy link
Collaborator Author

choldgraf commented Feb 8, 2023

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.

chrome_R2xBHhZEm9

@trallard
Copy link
Collaborator

trallard commented Feb 8, 2023

💀 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)
    Breadcrumbs_–_GOV_UK_Design_System

  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)
    color-contrast___-_CSS__Cascading_Style_Sheets___MDN

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

  4. GitHub -> breadcrumbs are styled as links except for the current page
    pydata-sphinx-theme_prerelease-template_md_at_main_·pydata_pydata-sphinx-theme·_GitHub

@choldgraf
Copy link
Collaborator Author

choldgraf commented Feb 8, 2023

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
Copy link
Collaborator Author

choldgraf commented Feb 8, 2023

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:

image

@trallard
Copy link
Collaborator

trallard commented Feb 8, 2023

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 drammock merged commit df125aa into pydata:main Feb 9, 2023
@drammock
Copy link
Collaborator

drammock commented Feb 9, 2023

Brilliant, thanks @choldgraf

12rambau added a commit to 12rambau/pydata-sphinx-theme that referenced this pull request Mar 2, 2023
* Fix extra whitespace in sidebars (pydata#1115)

* Fix extra whitespace in sidebars

* Searchbox

* Update src/pydata_sphinx_theme/__init__.py

Co-authored-by: Daniel McCloy <[email protected]>

* make test pass

* Fix template filter to remove empty files

* ABlog in template test

* Move clear search button to primary sidebar

* Move search clear button to top of article

Co-authored-by: Daniel McCloy <[email protected]>

* FIX: Use logo_url instead deprecated logo in theme (pydata#1094) (pydata#1097)

resolves pydata#1094

* ENH/MAINT: avoid overwriting the HtmlTranslator (pydata#1105)

Co-authored-by: Chris Holdgraf <[email protected]>
Fix pydata#143
Fix pydata#94

* fix: align sidebar sliding with the buttons (pydata#1123)

* fix: aline the sidebar sliding with the buttons

* build: force test to run on all platform
if one platform is failing we cannot see if it's platform related as the other were closed

* fix: use correct path for documentation logo

* MAINT: Improve font sizing (pydata#1129)

Fix pydata#1001

* MAINT: Refactor workflows to reduce test dependencies (pydata#1136)

* MAINT: update prerelease workflow (pydata#1140)

* ABlog: Updates for new HTML structure (pydata#1118)

* ABlog: Updates for new HTML structure

* Update templates for latest release

* Bump to dev0

* Standardize logo image behavior between Sphinx and this theme (pydata#1132)

Co-authored-by: Daniel McCloy <[email protected]>
Co-authored-by: Chris Holdgraf <[email protected]>
Co-authored-by: Chris Holdgraf <[email protected]>

* 0.13.0rc1

* Build(deps): Bump http-cache-semantics from 4.1.0 to 4.1.1 (pydata#1154)

* DOC: Use only shield.io for badges in README (pydata#1152)

* Copyright semicolon (pydata#1160)

* FIX: Flex behavior should shrink header items instead of brand (pydata#1158)

Co-authored-by: Chris Holdgraf <[email protected]>
Fixes pydata#1143

* STYLE: lint the documentation with Doc8 (pydata#1150)

Fix pydata#1139

* Add test for internationalization and translations (pydata#1138)

* FIX: Javascript incorrect check for variable (pydata#1166)

* MAINT: update pypi classifiers (pydata#1153)

Fix pydata#1106

* remove emoji from landing page (pydata#1151)

* add fa icons instead of emoji

* remove fix for emojis

* use markup for readme emojis

* use pst-color-primary instead of sd-text-primary

* make our semantic colors available as classes

* try again

---------

Co-authored-by: Daniel McCloy <[email protected]>

* FIX: Narrow scope of style rule for GitHub & GitLab link shortening (pydata#1167)

Fixes pydata#1156

* ENH: Add breadcrumbs to article header (pydata#1142)

* ENH: Add breadcrumbs to article header

* Update src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html

Co-authored-by: Tania Allard <[email protected]>

* More fixes

* Improving nested page behavior

* Documenting breadcrumbs

* Update src/pydata_sphinx_theme/assets/styles/components/_breadcrumbs.scss

Co-authored-by: Rambaud Pierrick <[email protected]>

* Breacrumbs have link color

---------

Co-authored-by: Tania Allard <[email protected]>
Co-authored-by: Rambaud Pierrick <[email protected]>

* Degrade gracefully when JavaScript is disabled (pydata#1146)

* Fix header vertical spacing and jupyter-sphinx cells (pydata#1164)

Fixes undefined

* RLS: v0.13.0rc2 (pydata#1170)

* DOCS: admonition customization (pydata#1155)

* first draft of the admonition customization

* typo in doc link

* flesh out admon. customization example; DRY

* use :code:rst instead of :literal:

* Update docs/_static/custom.css

---------

Co-authored-by: Daniel McCloy <[email protected]>

* Fix article header CSS (pydata#1171)

* “Edit this page” → “Edit on GitHub/GitLab/Bitbucket” (pydata#1177)

* “Edit this page” → “Edit on GitHub/GitLab/Bitbucket”

Fixes pydata#1172

* Add tests

* Fix typo

* Properly handle default_mode=auto when writing logos (pydata#1183)

We used to only defaulting to the light version when `default_mode` was
undefined, not when it was explicitly set to `auto`. We also need to
handle the latter, as the new test shows.

Closes pydata#1180

Co-authored-by: Jérémy Bobbio (Lunar) <[email protected]>

* fix: correctly add DOM listeners (pydata#1179)

fix adding DOM listeners

* maint: update GitLab URL tests (pydata#1186)

Co-authored-by: JoerivanEngelen <[email protected]>

* Standardize template structure in more sections (pydata#1184)

* Standardize template structure in all sections

* Fixing footer behavior

* Update docs/user_guide/layout.rst

Co-authored-by: Daniel McCloy <[email protected]>

* Remove use of id= as much as possible

---------

Co-authored-by: Daniel McCloy <[email protected]>

* maint: remove sphinx-panels support; remove deprecated config shims (pydata#1188)

* Minor style improvements to ablog (pydata#1185)

* RLS: v0.13.0rc3

* dev0

* FIX: Some style bugs (pydata#1191)

* FIX: Some style bugs

* Move link word wrap to global rule

* DOCS: Add internationalization instructions (pydata#1178)

Co-authored-by: James McKinney <[email protected]>

* Refactor contributing docs to be more modular (pydata#1173)

* Dev0

* Fix github gitlab brand (pydata#1194)

* RLS: v0.13.0rc4

* FIX: Make wide equations scroll (pydata#1196)

* Fix math scrollbars for realz (pydata#1198)

* Fix math scrollbars for realz

* Update src/pydata_sphinx_theme/assets/styles/content/_math.scss

* Update src/pydata_sphinx_theme/assets/styles/content/_math.scss

* copy_logo_images: do not render dynamic Sphinx template content (pydata#1204)

* copy_logo_images: do not render dynamic Sphinx template content when copying logo image files

* Update src/pydata_sphinx_theme/__init__.py

---------

Co-authored-by: Chris Holdgraf <[email protected]>

* Add conditional check for last-updated template (pydata#1201)

* Add conditional check for last-updated template

* Whitespace

* Properly set configuration with app.builder.theme_options (pydata#1199)

* Properly set configuration

* Dict to values

* Making it explicit in a function

* Better name

* Fix test

* Foot

* Revert complex config set

* Clarify docs

* Use CSS transform for skip link (pydata#1206)

* feat: Add full i18n support (pydata#1192)

Co-authored-by: Daniel McCloy <[email protected]>
Co-authored-by: James McKinney <[email protected]>
Co-authored-by: Chris Holdgraf <[email protected]>
Co-authored-by: Chris Holdgraf <[email protected]>

* Dev0

* FIX: Remove icon links component when no icon links given (pydata#1209)

* RLS: 0.13.0rc5

* dev0

* FIX: Get theme options in a more robust way (pydata#1214)

* RLS: v0.13.0rc6

* Make heading-style use the font-weight-heading value (pydata#1213)

* Make heading-style use the font-weight-heading value

* Separate font-weight setting for content headers and admonitions

* Flip var to be consistent with --pst-font-weight-heading instead

* RLS: v0.13.0

* bump: dev0

* DOCS: Remove <p> from announcement sample text (pydata#1223)

---------

Co-authored-by: Chris Holdgraf <[email protected]>
Co-authored-by: Daniel McCloy <[email protected]>
Co-authored-by: Nico Albers <[email protected]>
Co-authored-by: Chris Holdgraf <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Brendan Heberlein <[email protected]>
Co-authored-by: Tania Allard <[email protected]>
Co-authored-by: Lunar <[email protected]>
Co-authored-by: Jean Abou-Samra <[email protected]>
Co-authored-by: Jérémy Bobbio (Lunar) <[email protected]>
Co-authored-by: JoerivanEngelen <[email protected]>
Co-authored-by: James McKinney <[email protected]>
Co-authored-by: James Addison <[email protected]>
Co-authored-by: Veronica Berglyd Olsen <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Add breadcrumbs with links to parent pages in the article header
4 participants