diff --git a/docs/examples/subpages/index.rst b/docs/examples/subpages/index.rst index 068452e5a..d49126ce1 100644 --- 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 index b521913d6..77b5f509c 100644 --- 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 index f6c585a38..9521a33b6 100644 --- 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 index 0bd621128..fe89301c3 100644 --- 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 index a3f2fc809..33eebb71d 100644 --- 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 index 6c034c3f1..7fa2c41f0 100644 --- 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 index 5c7e39550..a49501b09 100644 --- 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 new file mode 100644 index 000000000..866e36f9b --- /dev/null +++ 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 index 925eb3778..cde41b4b9 100644 --- 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 index 5837dbf9a..044d966c4 100644 --- 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 new file mode 100644 index 000000000..6056f3cec --- /dev/null +++ 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 index 5de6eea20..c8e8b94d4 100644 --- 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 index 2a6b0456c..f7618ec4e 100644 --- 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 new file mode 100644 index 000000000..c9e9cf067 --- /dev/null +++ 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": ''}, parents[-1]] %} +{% endif %} + +{#- Hide breadcrumbs on the home page #} +{% if title and pagename != root_doc %} + +{% 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 index 00bdf56c4..7abad0e9e 100644 --- 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 -#} +
+ {% if theme_article_header_start %} +
+ {% for item in theme_article_header_start %} +
{% include item %}
+ {% endfor %} +
+ {% endif %} + {% if theme_article_header_end %} +
+ {% for item in theme_article_header_end %} +
{% include item %}
+ {% endfor %} +
+ {% endif %} +
diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf index 0df9b3f5e..c2b4ce1b1 100644 --- 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