ENH: Add breadcrumbs to article header

docs/examples/subpages/index.rst

@@ -1,4 +1,4 @@
-Section to show off pages with many sub-pages
+Section to show off pages with many sub pages
 =============================================
 
 To create an additional level of nesting in the sidebar, construct a

docs/examples/subpages/subpage1.rst

@@ -1,4 +1,4 @@
-Sub-page 1
+Sub page 1
 ==========
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec lorem neque, interdum in ipsum nec,

docs/examples/subpages/subpage2.rst

@@ -1,4 +1,4 @@
-Sub-page 2
+Sub page 2
 ==========
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec lorem neque, interdum in ipsum nec,

docs/examples/subpages/subsubpages/index.rst

@@ -1,4 +1,4 @@
-Section with sub-sub-pages
+Section with sub sub pages
 ==========================
 
 To create an additional level of nesting in the sidebar, construct a

docs/examples/subpages/subsubpages/subsubpage1.rst

@@ -1,4 +1,4 @@
-Sub-sub-page 1
+Sub sub page 1
 ==============
 
 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
 Suspendisse quis volutpat ipsum. Sed lobortis scelerisque tristique. Aenean condimentum risus tellus,
 quis accumsan ipsum laoreet ut. Integer porttitor maximus suscipit. Mauris in posuere sapien.
 Aliquam accumsan feugiat ligula, nec fringilla libero commodo sed. Proin et erat pharetra.
+
+.. toctree::
+
+   subsubsubpages/subsubsubpage1

docs/examples/subpages/subsubpages/subsubpage2.rst

@@ -1,4 +1,4 @@
-Sub-sub-page 2
+Sub sub page 2
 ==============
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec lorem neque, interdum in ipsum nec,

docs/examples/subpages/subsubpages/subsubpage3.rst

@@ -1,4 +1,4 @@
-Sub-sub-page 3
+Sub sub page 3
 ==============
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec lorem neque, interdum in ipsum nec,

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

@@ -0,0 +1,4 @@
+Sub sub sub page 1
+==================
+
+Test.

src/pydata_sphinx_theme/__init__.py

@@ -203,6 +203,8 @@ def update_and_remove_templates(app, pagename, templatename, context, doctree):
         "theme_navbar_center",
         "theme_navbar_persistent",
         "theme_navbar_end",
+        "theme_article_header_start",
+        "theme_article_header_end",
         "theme_footer_items",
         "theme_secondary_sidebar_items",
         "theme_primary_sidebar_end",

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

@@ -0,0 +1,38 @@
+/**
+ * Breadcrumbs for parent pages meant for the article header
+ */
+ul.bd-breadcrumbs {
+  list-style: none;
+  padding-left: 0;
+  display: flex;
+  flex-wrap: wrap;
+
+  // Font size slightly smaller to avoid cluttering up space too much
+  font-size: 0.8em;
+
+  li.breadcrumb-item {
+    display: flex;
+    align-items: center;
+
+    // Items that aren't the home have a carot to the left
+    &:not(.breadcrumb-home):before {
+      font-family: "Font Awesome 6 Free";
+      font-weight: 900;
+      font-size: 0.8rem;
+      content: var(--pst-breadcrumb-divider);
+      color: var(--pst-color-text-muted);
+      padding: 0 0.5rem;
+    }
+
+    // Breadcrumb links should behave like navbar links
+    a {
+      color: var(--pst-color-text-muted);
+      transition: color 0.25s ease-out;
+
+      &:hover {
+        color: var(--pst-color-primary);
+        text-decoration: none;
+      }
+    }
+  }
+}

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

@@ -32,6 +32,7 @@
 @import "./sections/sidebar-toggle";
 
 // Re-usable components across the theme
+@import "./components/breadcrumbs";
 @import "./components/icon-links";
 @import "./components/header/header-logo";
 @import "./components/navbar-links";

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

@@ -23,4 +23,7 @@ html {
   --pst-icon-share: "\f064"; // fa-solid fa-share
   --pst-icon-bell: "\f0f3"; // fa-solid fa-bell
   --pst-icon-pencil: "\f303"; // fa-solid fa-pencil
+
+  // Bootstrap icons
+  --pst-breadcrumb-divider: "\f105";
 }

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

@@ -0,0 +1,31 @@
+{%- block breadcrumbs %}
+{#
+  If we have more than 3 parents (excluding the home page) then we remove
+  The ones in the middle and add an ellipsis.
+#}
+{% if parents|length>2 %}
+{% set parents=[parents[0], {"title": '<i class="fa-solid fa-ellipsis"></i>'}, parents[-1]] %}
+{% endif %}
+
+{#- Hide breadcrumbs on the home page #}
+{% if title and pagename != root_doc %}
+<nav aria-label="breadcrumbs">
+  <ul class="bd-breadcrumbs" role="navigation" aria-label="Breadcrumb">
+    {# Home icon #}
+    <li class="breadcrumb-item breadcrumb-home">
+      <a href="{{ pathto(root_doc) }}" class="nav-link" aria-label="Home">
+        <i class="fa-solid fa-home"></i>
+      </a>
+    </li>
+    {%- for doc in parents %}
+    {% if doc.link %}
+    <li class="breadcrumb-item"><a href="{{ doc.link|e }}" class="nav-link">{{ doc.title }}</a></li>
+    {% else %}
+    <li class="breadcrumb-item">{{ doc.title }}</li>
+    {% endif %}
+    {%- endfor %}
+    <li class="breadcrumb-item active" aria-current="page">{{ title }}</li>
+  </ul>
+</nav>
+{% endif %}
+{%- endblock %}

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

@@ -1 +1,16 @@
-{#- Intentionally empty in case others want to add something -#}
+<div class="header-article-items header-article__section">
+  {% if theme_article_header_start %}
+    <div class="header-article-items__start">
+      {% for item in theme_article_header_start %}
+        <div class="header-article-start-item">{% include item %}</div>
+      {% endfor %}
+    </div>
+  {% endif %}
+  {% if theme_article_header_end %}
+    <div class="header-article-items__end">
+      {% for item in theme_article_header_end %}
+        <div class="header-article-end-item">{% include item %}</div>
+      {% endfor %}
+    </div>
+  {% endif %}
+</div>

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf

@@ -32,6 +32,8 @@ navbar_start = navbar-logo.html
 navbar_center = navbar-nav.html
 navbar_end = theme-switcher.html, navbar-icon-links.html
 navbar_persistent = search-button.html
+article_header_start = breadcrumbs.html
+article_header_end =
 header_links_before_dropdown = 5
 primary_sidebar_end = sidebar-ethical-ads.html
 footer_items = copyright.html, theme-version.html, sphinx-version.html