Allow customizing sidebar (#124)

wagtail · Nov 30, 2021 · e471301 · e471301
1 parent b655e9f
commit e471301
Show file tree

Hide file tree

Showing 4 changed files with 42 additions and 13 deletions.
diff --git a/docs/customizing.rst b/docs/customizing.rst
@@ -105,7 +105,7 @@ relevant rules:
    /* Import from Google Fonts, a CDN, or files in your _static folder.
       This Google Fonts import provides its own `@font-face` CSS;
       if providing your own font files, you'll also need to
-      provide your own @font-face` code. */
+      provide your own `@font-face` code. */
    @import url("https://fonts.googleapis.com/css2?family=Roboto");
 
    /* Main font used throughout the docs. */
@@ -117,3 +117,35 @@ relevant rules:
    pre, code, kbd, samp {
      font-family: "Courier New", monospace;
    }
+
+Customize the Sidebar
+---------------------
+
+To change the contents of the sidebar, create a custom HTML template and specify
+it in ``conf.py``. For example, let's add a link to sponsor your project below
+the table of contents tree:
+
+.. code-block:: python
+
+   # Add any relative paths that contain templates.
+   templates_path = ["_templates"]
+
+   # Custom sidebar templates, must be a dictionary that maps document names
+   # to template names. "**" will apply the templates to all pages.
+   # The theme default is just searchbox and globaltoc.
+   html_sidebars = {"**": [
+       "searchbox.html",
+       "globaltoc.html",
+       "custom.html",    # Your template here
+   ]}
+
+Then in ``_templates/custom.html``:
+
+.. code-block:: html
+
+   <p>
+     Sponsor my project!
+     <a href="http://example.com">Here's the link</a>
+   </p>
+
+Read more about `customizing the sidebar in Sphinx <https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_sidebars>`_
diff --git a/sphinx_wagtail_theme/globaltoc.html b/sphinx_wagtail_theme/globaltoc.html
@@ -0,0 +1,5 @@
+<div class="site-toc">
+    <nav class="toc mt-3" aria-label="Main menu">
+        {{ toctree(includehidden=False, collapse=False, maxdepth=8, titles_only=True) }}
+    </nav>
+</div>
diff --git a/sphinx_wagtail_theme/layout.html b/sphinx_wagtail_theme/layout.html
@@ -110,17 +110,9 @@
         <div class="row">
             <aside class="col-12 col-lg-3">
                 <div id="collapseSidebar" class="collapse sticky-top d-lg-block pt-5">
-                    {%- if not theme_is_homepage and builder == 'html' %}
-                        {%- include "searchbox.html" %}
-                    {%- endif %}
-                    <div class="site-toc">
-                        <nav class="toc mt-3" aria-label="Main menu">
-                            {%- set toctree = toctree(maxdepth=8, collapse=False, includehidden=False, titles_only=True) -%}
-                            {%- if toctree %}
-                                {{ toctree }}
-                            {%- endif %}
-                        </nav>
-                    </div>
+                    {%- for sidebartemplate in sidebars %}
+                    {%- include sidebartemplate %}
+                    {%- endfor %}
                     <div class="d-lg-none border-bottom">
                         {# Bottom border for mobile (above content, needs to be expanded.) #}
                     </div>

diff --git a/sphinx_wagtail_theme/theme.conf b/sphinx_wagtail_theme/theme.conf
@@ -1,10 +1,10 @@
 [theme]
 inherit = none
+sidebars = searchbox.html, globaltoc.html
 stylesheet = dist/theme.css
 pygments_style = none
 
 [options]
-is_homepage =
 project_name = Sphinx Wagtail Theme
 logo = img/wagtail-logo-new.svg
 logo_alt = Wagtail