using sphinx sidebars

docs/conf.py

@@ -87,7 +87,7 @@
     # For testing
     # "home_page_in_toc": True,
     # "single_page": True,
-    # "extra_footer": "<a href='https://google.com'>Test</a>",
+    # "extra_footer": "<a href='https://google.com'>Test</a>",  # DEPRECATED KEY
     # "extra_navbar": "<a href='https://google.com'>Test</a>",
 }
 html_baseurl = "https://sphinx-book-theme.readthedocs.io/en/latest/"

docs/layout.md

@@ -226,7 +226,7 @@ but I'll stop here.
 
 You can control some elements of the navigation bar. Here are the main features:
 
-### Expand sections of your navbar
+### Expand sections of your sidebar
 
 You can keep certain sub-sections of pages to be permanently expanded in your
 left Table of Contents. To do so, add a list of any pages you wish to be expanded
@@ -260,6 +260,41 @@ html_theme_options = {
 }
 ```
 
+## Control the left sidebar
+
+You can control what kind of content goes underneath the logo and name of your website in the top left.
+
+To do so, use the `html_sidebars` variable in your `conf.py` file. This takes a dictionary of filename patterns as keys, and a list of sidebar elements as values. Any files that match a key will have the corresponding sidebar elements placed in that page's sidebar.
+
+For example, the following configuration would include *only the footer* on pages under the `posts/` folder:
+
+```python
+html_sidebars = {
+    "posts/*": ["sbt-sidebar-footer.html"]
+}
+```
+
+See the [Sphinx HTML sidebars documentation](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_sidebars) for more information.
+
+### Default sidebar elements
+
+By default, this theme comes with these three theme-specific sidebar elements enabled on all pages:
+
+- `sidebar-search-bs.html`: A bootstrap-based search bar (from the [PyData Sphinx Theme](https://pydata-sphinx-theme.readthedocs.io/))
+- `sbt-sidebar-nav.html`: A bootstrap-based navigation menu for your book.
+- `sbt-sidebar-footer`: A [configurable](custom-footer) snippet of HTML to add to the sidebar (by default it is placed at the bottom).
+
+(custom-footer)=
+## Customize the sidebar footer
+
+You may choose your own HTML to include in the footer of your sidebar (or set it to be empty). To do so, use the following configuration variable in `conf.py`:
+
+```python
+extra_sidebar = "<p>Your HTML</p>"
+```
+
+This text will be placed at the bottom of the sidebar by default.
+
 ## Add metadata open graph tags to your site
 
 OpenGraph tags can be used to generate previews and descriptions of your

sphinx_book_theme/__init__.py

@@ -391,6 +391,9 @@ def setup(app: Sphinx):
 
     app.add_directive("margin", Margin)
 
+    # Update templates for sidebar
+    app.config.templates_path.append(os.path.join(package_dir, "_templates"))
+
     return {
         "parallel_read_safe": True,
         "parallel_write_safe": True,

sphinx_book_theme/_templates/sbt-sidebar-footer.html

@@ -0,0 +1,6 @@
+{% if theme_navbar_footer_text %}{% set theme_extra_navbar=theme_navbar_footer_text %}{% endif %} <!-- To handle the deprecated key -->
+{% if theme_extra_navbar %}
+<div class="navbar_extra_footer">
+  {{ theme_extra_navbar }}
+</div>
+{% endif %}

sphinx_book_theme/_templates/sbt-sidebar-nav.html

@@ -0,0 +1,3 @@
+<nav class="bd-links" id="bd-docs-nav" aria-label="Main navigation">
+    {{ generate_nav_html(include_item_names=True, with_home_page=theme_home_page_in_toc) }}
+</nav>

sphinx_book_theme/sidebar.html

@@ -9,18 +9,7 @@ <h1 class="site-logo" id="site-title">{{ docstitle }}</h1>
 </a>
 </div>
 
-<form class="bd-search d-flex align-items-center" action="{{ pathto('search') }}" method="get">
-  <i class="icon fas fa-search"></i>
-  <input type="search" class="form-control" name="q" id="search-input" placeholder="{{ theme_search_bar_text }}" aria-label="{{ theme_search_bar_text }}" autocomplete="off" >
-</form>
 
-<nav class="bd-links" id="bd-docs-nav" aria-label="Main navigation">
-  {{ generate_nav_html(include_item_names=True, with_home_page=theme_home_page_in_toc) }}
-</nav>
-
-{% if theme_navbar_footer_text %}{% set theme_extra_navbar=theme_navbar_footer_text %}{% endif %} <!-- To handle the deprecated key -->
-{% if theme_extra_navbar %}
-<div class="navbar_extra_footer">
-  {{ theme_extra_navbar }}
-</div>
-{% endif %}
+{%- for sidebartemplate in sidebars %}
+{%- include sidebartemplate %}
+{%- endfor %}

sphinx_book_theme/theme.conf

@@ -2,6 +2,7 @@
 [theme]
 inherit = pydata_sphinx_theme
 pygments_style = tango
+sidebars = sidebar-search-bs.html, sbt-navbar-nav.html, sbt-navbar-footer.html
 stylesheet = sphinx-book-theme.c73dba93dc14e2148248cba6cd058605.css
 
 [options]

src/jinja/theme.conf.j2

@@ -2,6 +2,7 @@
 [theme]
 inherit = pydata_sphinx_theme
 pygments_style = tango
+sidebars = sidebar-search-bs.html, sbt-navbar-nav.html, sbt-navbar-footer.html
 stylesheet = {{ "src/scss/sphinx-book-theme.scss" | compiled_name }}
 
 [options]