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 <taniar.allard@gmail.com> * More fixes * Improving nested page behavior * Documenting breadcrumbs * Update src/pydata_sphinx_theme/assets/styles/components/_breadcrumbs.scss Co-authored-by: Rambaud Pierrick <12rambau@users.noreply.github.com> * Breacrumbs have link color --------- Co-authored-by: Tania Allard <taniar.allard@gmail.com> Co-authored-by: Rambaud Pierrick <12rambau@users.noreply.github.com>
pydata · Feb 9, 2023 · df125aa · df125aa
1 parent 3a59b4e
commit df125aa
Show file tree

Hide file tree

Showing 16 changed files with 124 additions and 10 deletions.
diff --git a/docs/examples/subpages/index.rst b/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

diff --git a/docs/examples/subpages/subpage1.rst b/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,

diff --git a/docs/examples/subpages/subpage2.rst b/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,

diff --git a/docs/examples/subpages/subsubpages/index.rst b/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

diff --git a/docs/examples/subpages/subsubpages/subsubpage1.rst b/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
diff --git a/docs/examples/subpages/subsubpages/subsubpage2.rst b/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,

diff --git a/docs/examples/subpages/subsubpages/subsubpage3.rst b/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,

diff --git a/docs/examples/subpages/subsubpages/subsubsubpages/subsubsubpage1.rst b/docs/examples/subpages/subsubpages/subsubsubpages/subsubsubpage1.rst
@@ -0,0 +1,4 @@
+Sub sub sub page 1
+==================
+
+Test.
diff --git a/docs/user_guide/layout.rst b/docs/user_guide/layout.rst
@@ -192,8 +192,9 @@ which they appear. This page describes the major areas that you can customize.
 Header / Navigation Bar
 =======================
 
-The header is at the top of the page above all other content, and contains site-level information.
+Located in ``sections/header.html``.
 
+The header is at the top of the page above all other content, and contains site-level information.
 
 Header sections
 ---------------
@@ -264,14 +265,23 @@ If you'd like these items to snap to the right of the page, use this configurati
 Article Header
 ==============
 
+Located in ``sections/header-article.html``.
+
 The article header is a narrow bar just above the article's content.
-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.
+There are two sub-sections that can have component templates added to them:
+
+- ``article_header_start`` is aligned to the beginning (left) of the article header.
+  By default, this section has the ``breadcrumbs.html`` component which displays links to parent pages of the current page.
+- ``article_header_end`` is aligned to the end (right) of the article header.
+  By default, this section is empty.
 
 .. _layout-sidebar-primary:
 
 Primary sidebar (left)
 ======================
 
+Located in ``sections/sidebar-primary.html``.
+
 The primary sidebar is just to the left of a page's main content.
 It is primarily used for between-section navigation.
 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:
 Footer Content
 ==============
 
+Located in ``sections/footer-content.html``.
+
 The footer content is a narrow bar spanning the article’s content and secondary sidebar.
 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.
 
@@ -367,6 +379,8 @@ It does not contain anything immediately viewable to the reader, but is kept as
 Secondary Sidebar (right)
 =========================
 
+Located in ``sections/sidebar-secondary.html``.
+
 The in-page sidebar is just to the right of a page's article content, and is
 configured in ``conf.py`` with ``html_theme_options['secondary_sidebar_items']``.
 
@@ -387,6 +401,8 @@ To learn how to further customize or remove the secondary sidebar, please check
 Article Footer
 ==============
 
+Located in ``sections/footer-article.html``.
+
 The article footer exists just below your page's article, and is primarily used for navigating between adjacent sections / pages.
 
 Hide the previous and next buttons
@@ -406,6 +422,8 @@ at the bottom. You can hide these buttons with the following configuration:
 Footer
 ======
 
+Located in ``sections/footer.html``.
+
 The footer is just below a page’s main content, and is configured in ``conf.py``
 with ``html_theme_options['footer_items']``.
 
@@ -451,6 +469,7 @@ will be named accordingly).
 
 .. refer to files in: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/
 
+- ``breadcrumbs.html``
 - ``copyright.html``
 - ``edit-this-page.html``
 - ``footer-article/prev-next.html``

diff --git a/src/pydata_sphinx_theme/__init__.py b/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",

diff --git a/src/pydata_sphinx_theme/assets/styles/components/_breadcrumbs.scss b/src/pydata_sphinx_theme/assets/styles/components/_breadcrumbs.scss
@@ -0,0 +1,33 @@
+/**
+ * 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.8rem;
+
+  li.breadcrumb-item {
+    display: flex;
+    align-items: center;
+
+    // Style should look like heavier in-page links
+    font-weight: bold;
+    a {
+      color: var(--pst-color-link);
+    }
+
+    // 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;
+    }
+  }
+}
diff --git a/src/pydata_sphinx_theme/assets/styles/pydata-sphinx-theme.scss b/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";

diff --git a/src/pydata_sphinx_theme/assets/styles/variables/_icons.scss b/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";
 }
diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html b/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 %}
diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/header-article.html b/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>
diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf b/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