Skip to content

Commit aac71f1

Browse files
Fix the stickiness of the version warning banner, and rename the config option to sticky_banners (#2385)
This PR renames the `sticky_version_warning_banner` theme configuration option to `sticky_banners` and fixes issues reported in #2328 after the initial fix landed in #2372. The fix is that the stickiness moves one level up. I've added `.pst-sticky-header` which wraps both the `.pst-async-banner-revealer` banner and the `.bd-header` navbar. The rule also overrides `.bd-header { position: sticky }` for the navbar inside the wrapper to neutralise its effect. **[EDIT: Resolved!]** ~There is no behaviour change besides the fix, but I do have some additional thoughts below: #2385 (comment) Closes #2328 ### Some screenshots <details><summary>Click to expand</summary> <p> | Scenario | Screenshot | |--------|--------| | Default view on the home page | <img width="5088" height="2978" alt="Default view on the home page" src="https://github.com/user-attachments/assets/f00bfdef-d2c2-47bc-990d-546574e63e33" /> | | Scrolled down on the home page, the version warning banner still remains sticky | <img width="5088" height="2978" alt="image" src="https://github.com/user-attachments/assets/c6d07c6d-a8b6-41f8-92a3-732b7d8de6e5" /> | | Navigated to a new page that's not the home page | <img width="5088" height="2978" alt="image" src="https://github.com/user-attachments/assets/e54b0c86-573d-40ac-b25e-bab093cd1bdc" /> | | Navigated to a new page that's not the home page, and scrolled down from the top | <img width="5088" height="2978" alt="image" src="https://github.com/user-attachments/assets/130a4919-4acc-410d-ab0f-c80f31d45b15" /> | | Navigated to a new page that's not the home page, with the announcement banner checked off, default view | <img width="5088" height="2978" alt="image" src="https://github.com/user-attachments/assets/6767943d-c988-4841-a06f-0002bcc2c8be" /> | | Navigated to a new page that's not the home page, with the announcement banner checked off, and scrolled down from the top | <img width="5088" height="2978" alt="image" src="https://github.com/user-attachments/assets/58041152-c583-47f3-855c-b77bc5d37849" /> | </p> </details>
1 parent 5d30788 commit aac71f1

7 files changed

Lines changed: 46 additions & 30 deletions

File tree

‎docs/user_guide/announcements.rst‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -94,23 +94,25 @@ In addition to the general-purpose announcement banner, the theme includes a bui
9494
version compares greater than the preferred version (or if the version match contains the strings `"dev"`,
9595
`"rc"` or `"pre"`), the announcement will say they are viewing an unstable development version instead.
9696

97-
Stick the warning banner to the top of the viewport
98-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
97+
Stick banners to the top of the viewport
98+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9999

100100
By default the version warning banner scrolls off-screen with the rest of the page,
101101
which can hide the warning when users land on a deep-link inside an old-version page.
102-
To keep the banner visible while users scroll, set:
102+
To keep the version warning banner and the announcement banner pinned to the top of
103+
the viewport while users scroll, set:
103104

104105
.. code-block:: python
105106
:caption: conf.py
106107
107108
html_theme_options = {
108109
...
109-
"sticky_version_warning_banner": True,
110+
"sticky_banners": True,
110111
}
111112
112-
This sticks the entire banner wrapper (version warning plus any announcement)
113-
to the top of the viewport. Default is ``False``.
113+
This pins both the version warning banner and the announcement banner (whether
114+
local or remote) above the navbar at the top of the viewport. Default is
115+
``False``.
114116

115117
If you want similar functionality for *older* versions of your docs (i.e. those built before the ``show_version_warning_banner`` configuration option was available), you can manually add a banner by prepending the following HTML to all pages (be sure to replace ``URL_OF_STABLE_VERSION_OF_PROJECT`` with a valid URL, and adjust styling as desired):
116118

‎src/pydata_sphinx_theme/assets/styles/sections/_announcement.scss‎

Lines changed: 0 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -13,14 +13,6 @@
1313
}
1414
}
1515

16-
.pst-async-banner-revealer.pst-sticky-banners {
17-
position: sticky;
18-
top: 0;
19-
20-
// Above the fixed header (which uses z-index inside the bd-navbar).
21-
z-index: 1030;
22-
}
23-
2416
#bd-header-version-warning,
2517
.bd-header-announcement {
2618
min-height: 3rem;

‎src/pydata_sphinx_theme/assets/styles/sections/_header.scss‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,20 @@
55

66
// Styling for the Icon links can be found in components/_icon-links.scss
77

8+
// A wrapper used when `sticky_banners` is enabled. It pins the announcement /
9+
// version-warning banners and the navbar at the top of the viewport.
10+
.pst-sticky-header {
11+
position: sticky;
12+
top: 0;
13+
z-index: $zindex-fixed;
14+
15+
// The .bd-header (top navbar) inside the wrapper must not be sticky on its
16+
// own, as .pst-sticky-header above is already sticky.
17+
.bd-header {
18+
position: static;
19+
}
20+
}
21+
822
// If we want the shadow to only point downward in the future, set
923
// box-shadow to: 0 0.125rem 0.25rem -0.125rem rgba(0, 0, 0, 0.11);
1024
.bd-header {

‎src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,11 @@
8181
{%- endif %}
8282
{%- endblock search_dialog %}
8383

84+
{%- set pst_stick_banners = theme_sticky_banners | tobool -%}
85+
{%- if pst_stick_banners %}
86+
<div class="pst-sticky-header">
87+
{%- endif %}
88+
8489
{% include "sections/announcement.html" %}
8590

8691
{% block docs_navbar %}
@@ -89,6 +94,10 @@
8994
</header>
9095
{% endblock docs_navbar %}
9196

97+
{%- if pst_stick_banners %}
98+
</div>
99+
{%- endif %}
100+
92101
<div class="bd-container">
93102
<div class="bd-container__inner bd-page-width">
94103
{# Primary sidebar #}

‎src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/announcement.html‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,5 @@
11
{#- The "revealer" allows async banners to be loaded, revealed, and animated together in a controlled way -#}
2-
{%- set revealer_classes = "pst-async-banner-revealer d-none" -%}
3-
{%- if theme_sticky_version_warning_banner | tobool -%}
4-
{%- set revealer_classes = revealer_classes + " pst-sticky-banners" -%}
5-
{%- endif -%}
6-
<div class="{{ revealer_classes }}">
2+
<div class="pst-async-banner-revealer d-none">
73
{#- Version warning banner is always loaded remotely/asynchronously #}
84
<aside id="bd-header-version-warning" class="d-none d-print-none" aria-label="{{ _('Version warning') }}"></aside>
95
{#- But the announcement banner might be loaded locally or remotely -#}

‎src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ footer_center =
5555
footer_end = theme-version
5656
secondary_sidebar_items = page-toc, edit-this-page, sourcelink
5757
show_version_warning_banner = False
58-
sticky_version_warning_banner = False
58+
sticky_banners = False
5959
announcement =
6060

6161
# DEPRECATED (remove after 1.0 release)

‎tests/test_build.py‎

Lines changed: 13 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -352,27 +352,30 @@ def test_remote_announcement_banner(sphinx_build_factory) -> None:
352352
assert "pst-async-banner-revealer" in banner.parent["class"]
353353

354354

355-
def test_sticky_version_warning_banner_on(sphinx_build_factory) -> None:
356-
"""When the option is True, the revealer carries the sticky class."""
355+
def test_sticky_banners_on(sphinx_build_factory) -> None:
356+
"""When the option is True, the banner and the navbar are wrapped in a
357+
sticky container.
358+
"""
357359
confoverrides = {
358-
"html_theme_options.sticky_version_warning_banner": True,
360+
"html_theme_options.sticky_banners": True,
359361
}
360362
sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides).build()
361363
index_html = sphinx_build.html_tree("index.html")
362-
results = index_html.find_all(class_="pst-async-banner-revealer")
364+
wrappers = index_html.find_all(class_="pst-sticky-header")
363365

364-
assert len(results) == 1
365-
assert "pst-sticky-banners" in results[0]["class"]
366+
assert len(wrappers) == 1
367+
wrapper = wrappers[0]
368+
assert wrapper.find(class_="pst-async-banner-revealer") is not None
369+
assert wrapper.find(id="pst-header") is not None
366370

367371

368-
def test_sticky_version_warning_banner_default_off(sphinx_build_factory) -> None:
372+
def test_sticky_banners_default_off(sphinx_build_factory) -> None:
369373
"""The sticky class is absent by default (no behavior change for existing users)."""
370374
sphinx_build = sphinx_build_factory("base").build()
371375
index_html = sphinx_build.html_tree("index.html")
372-
results = index_html.find_all(class_="pst-async-banner-revealer")
373376

374-
assert len(results) == 1
375-
assert "pst-sticky-banners" not in results[0]["class"]
377+
assert not index_html.find_all(class_="pst-sticky-header")
378+
assert len(index_html.find_all(class_="pst-async-banner-revealer")) == 1
376379

377380

378381
@pytest.mark.parametrize(

0 commit comments

Comments
 (0)