Skip to content

Commit df125aa

Browse files
choldgraftrallard12rambau
authored
ENH: Add breadcrumbs to article header (#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]>
1 parent 3a59b4e commit df125aa

File tree

16 files changed

+124
-10
lines changed

16 files changed

+124
-10
lines changed

‎docs/examples/subpages/index.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Section to show off pages with many sub-pages
1+
Section to show off pages with many sub pages
22
=============================================
33

44
To create an additional level of nesting in the sidebar, construct a

‎docs/examples/subpages/subpage1.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Sub-page 1
1+
Sub page 1
22
==========
33

44
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec lorem neque, interdum in ipsum nec,

‎docs/examples/subpages/subpage2.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Sub-page 2
1+
Sub page 2
22
==========
33

44
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec lorem neque, interdum in ipsum nec,

‎docs/examples/subpages/subsubpages/index.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Section with sub-sub-pages
1+
Section with sub sub pages
22
==========================
33

44
To create an additional level of nesting in the sidebar, construct a

‎docs/examples/subpages/subsubpages/subsubpage1.rst

+5-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Sub-sub-page 1
1+
Sub sub page 1
22
==============
33

44
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec lorem neque, interdum in ipsum nec,
@@ -7,3 +7,7 @@ gravida nisl. Praesent aliquet odio eget libero elementum, quis rhoncus tellus t
77
Suspendisse quis volutpat ipsum. Sed lobortis scelerisque tristique. Aenean condimentum risus tellus,
88
quis accumsan ipsum laoreet ut. Integer porttitor maximus suscipit. Mauris in posuere sapien.
99
Aliquam accumsan feugiat ligula, nec fringilla libero commodo sed. Proin et erat pharetra.
10+
11+
.. toctree::
12+
13+
subsubsubpages/subsubsubpage1

‎docs/examples/subpages/subsubpages/subsubpage2.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Sub-sub-page 2
1+
Sub sub page 2
22
==============
33

44
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec lorem neque, interdum in ipsum nec,

‎docs/examples/subpages/subsubpages/subsubpage3.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Sub-sub-page 3
1+
Sub sub page 3
22
==============
33

44
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec lorem neque, interdum in ipsum nec,

‎docs/examples/subpages/subsubpages/subsubsubpages/subsubsubpage1.rst

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Sub sub sub page 1
2+
==================
3+
4+
Test.

‎docs/user_guide/layout.rst

+21-2
Original file line numberDiff line numberDiff line change
@@ -192,8 +192,9 @@ which they appear. This page describes the major areas that you can customize.
192192
Header / Navigation Bar
193193
=======================
194194

195-
The header is at the top of the page above all other content, and contains site-level information.
195+
Located in ``sections/header.html``.
196196

197+
The header is at the top of the page above all other content, and contains site-level information.
197198

198199
Header sections
199200
---------------
@@ -264,14 +265,23 @@ If you'd like these items to snap to the right of the page, use this configurati
264265
Article Header
265266
==============
266267

268+
Located in ``sections/header-article.html``.
269+
267270
The article header is a narrow bar just above the article's content.
268-
It does not contain anything immediately viewable to the reader, but is kept as a placeholder in case theme developers wish to re-use it in the future.
271+
There are two sub-sections that can have component templates added to them:
272+
273+
- ``article_header_start`` is aligned to the beginning (left) of the article header.
274+
By default, this section has the ``breadcrumbs.html`` component which displays links to parent pages of the current page.
275+
- ``article_header_end`` is aligned to the end (right) of the article header.
276+
By default, this section is empty.
269277

270278
.. _layout-sidebar-primary:
271279

272280
Primary sidebar (left)
273281
======================
274282

283+
Located in ``sections/sidebar-primary.html``.
284+
275285
The primary sidebar is just to the left of a page's main content.
276286
It is primarily used for between-section navigation.
277287
By default it will show links to any sublings / children of the current active top-level section (corresponding to links in your header navigation bar).
@@ -358,6 +368,8 @@ use this pattern:
358368
Footer Content
359369
==============
360370

371+
Located in ``sections/footer-content.html``.
372+
361373
The footer content is a narrow bar spanning the article’s content and secondary sidebar.
362374
It does not contain anything immediately viewable to the reader, but is kept as a placeholder in case theme developers wish to re-use it in the future.
363375

@@ -367,6 +379,8 @@ It does not contain anything immediately viewable to the reader, but is kept as
367379
Secondary Sidebar (right)
368380
=========================
369381

382+
Located in ``sections/sidebar-secondary.html``.
383+
370384
The in-page sidebar is just to the right of a page's article content, and is
371385
configured in ``conf.py`` with ``html_theme_options['secondary_sidebar_items']``.
372386

@@ -387,6 +401,8 @@ To learn how to further customize or remove the secondary sidebar, please check
387401
Article Footer
388402
==============
389403

404+
Located in ``sections/footer-article.html``.
405+
390406
The article footer exists just below your page's article, and is primarily used for navigating between adjacent sections / pages.
391407

392408
Hide the previous and next buttons
@@ -406,6 +422,8 @@ at the bottom. You can hide these buttons with the following configuration:
406422
Footer
407423
======
408424

425+
Located in ``sections/footer.html``.
426+
409427
The footer is just below a page’s main content, and is configured in ``conf.py``
410428
with ``html_theme_options['footer_items']``.
411429

@@ -451,6 +469,7 @@ will be named accordingly).
451469

452470
.. refer to files in: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/
453471
472+
- ``breadcrumbs.html``
454473
- ``copyright.html``
455474
- ``edit-this-page.html``
456475
- ``footer-article/prev-next.html``

‎src/pydata_sphinx_theme/__init__.py

+2
Original file line numberDiff line numberDiff line change
@@ -203,6 +203,8 @@ def update_and_remove_templates(app, pagename, templatename, context, doctree):
203203
"theme_navbar_center",
204204
"theme_navbar_persistent",
205205
"theme_navbar_end",
206+
"theme_article_header_start",
207+
"theme_article_header_end",
206208
"theme_footer_items",
207209
"theme_secondary_sidebar_items",
208210
"theme_primary_sidebar_end",

‎src/pydata_sphinx_theme/assets/styles/components/_breadcrumbs.scss

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
/**
2+
* Breadcrumbs for parent pages meant for the article header
3+
*/
4+
ul.bd-breadcrumbs {
5+
list-style: none;
6+
padding-left: 0;
7+
display: flex;
8+
flex-wrap: wrap;
9+
10+
// Font size slightly smaller to avoid cluttering up space too much
11+
font-size: 0.8rem;
12+
13+
li.breadcrumb-item {
14+
display: flex;
15+
align-items: center;
16+
17+
// Style should look like heavier in-page links
18+
font-weight: bold;
19+
a {
20+
color: var(--pst-color-link);
21+
}
22+
23+
// Items that aren't the home have a carot to the left
24+
&:not(.breadcrumb-home):before {
25+
font-family: "Font Awesome 6 Free";
26+
font-weight: 900;
27+
font-size: 0.8rem;
28+
content: var(--pst-breadcrumb-divider);
29+
color: var(--pst-color-text-muted);
30+
padding: 0 0.5rem;
31+
}
32+
}
33+
}

‎src/pydata_sphinx_theme/assets/styles/pydata-sphinx-theme.scss

+1
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@
3232
@import "./sections/sidebar-toggle";
3333

3434
// Re-usable components across the theme
35+
@import "./components/breadcrumbs";
3536
@import "./components/icon-links";
3637
@import "./components/header/header-logo";
3738
@import "./components/navbar-links";

‎src/pydata_sphinx_theme/assets/styles/variables/_icons.scss

+3
Original file line numberDiff line numberDiff line change
@@ -23,4 +23,7 @@ html {
2323
--pst-icon-share: "\f064"; // fa-solid fa-share
2424
--pst-icon-bell: "\f0f3"; // fa-solid fa-bell
2525
--pst-icon-pencil: "\f303"; // fa-solid fa-pencil
26+
27+
// Bootstrap icons
28+
--pst-breadcrumb-divider: "\f105";
2629
}

‎src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
{%- block breadcrumbs %}
2+
{#
3+
If we have more than 3 parents (excluding the home page) then we remove
4+
The ones in the middle and add an ellipsis.
5+
#}
6+
{% if parents|length>2 %}
7+
{% set parents=[parents[0], {"title": '<i class="fa-solid fa-ellipsis"></i>'}, parents[-1]] %}
8+
{% endif %}
9+
10+
{#- Hide breadcrumbs on the home page #}
11+
{% if title and pagename != root_doc %}
12+
<nav aria-label="breadcrumbs">
13+
<ul class="bd-breadcrumbs" role="navigation" aria-label="Breadcrumb">
14+
{# Home icon #}
15+
<li class="breadcrumb-item breadcrumb-home">
16+
<a href="{{ pathto(root_doc) }}" class="nav-link" aria-label="Home">
17+
<i class="fa-solid fa-home"></i>
18+
</a>
19+
</li>
20+
{%- for doc in parents %}
21+
{% if doc.link %}
22+
<li class="breadcrumb-item"><a href="{{ doc.link|e }}" class="nav-link">{{ doc.title }}</a></li>
23+
{% else %}
24+
<li class="breadcrumb-item">{{ doc.title }}</li>
25+
{% endif %}
26+
{%- endfor %}
27+
<li class="breadcrumb-item active" aria-current="page">{{ title }}</li>
28+
</ul>
29+
</nav>
30+
{% endif %}
31+
{%- endblock %}

‎src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/header-article.html

+16-1
Original file line numberDiff line numberDiff line change
@@ -1 +1,16 @@
1-
{#- Intentionally empty in case others want to add something -#}
1+
<div class="header-article-items header-article__section">
2+
{% if theme_article_header_start %}
3+
<div class="header-article-items__start">
4+
{% for item in theme_article_header_start %}
5+
<div class="header-article-start-item">{% include item %}</div>
6+
{% endfor %}
7+
</div>
8+
{% endif %}
9+
{% if theme_article_header_end %}
10+
<div class="header-article-items__end">
11+
{% for item in theme_article_header_end %}
12+
<div class="header-article-end-item">{% include item %}</div>
13+
{% endfor %}
14+
</div>
15+
{% endif %}
16+
</div>

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

+2
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,8 @@ navbar_start = navbar-logo.html
3232
navbar_center = navbar-nav.html
3333
navbar_end = theme-switcher.html, navbar-icon-links.html
3434
navbar_persistent = search-button.html
35+
article_header_start = breadcrumbs.html
36+
article_header_end =
3537
header_links_before_dropdown = 5
3638
primary_sidebar_end = sidebar-ethical-ads.html
3739
footer_items = copyright.html, theme-version.html, sphinx-version.html

0 commit comments

Comments
 (0)