`` will have their respective templates
inserted. You can also ``*`` to do ``glob``-style matching, and may use ``**``
to match all pages.
By default, it has the following configuration:
.. code-block:: python
html_sidebars = {
"**": ["sidebar-collapse", "sidebar-nav-bs"]
}
- ``sidebar-collapse.html`` - a button that allows users to expand and collapse the sidebar.
- ``sidebar-nav-bs.html`` - a bootstrap-friendly navigation section.
When there are no pages to show, it will disappear and potentially add extra space for your page's content.
Primary sidebar end sections
----------------------------
There is a special ```` within the primary sidebar that appears at the
bottom of the page, regardless of the content that is above it.
To control the HTML templates that are within this div, use
``html_theme_options['primary_sidebar_end']`` in ``conf.py``.
By default, it has the following templates:
.. code-block:: python
html_theme_options = {
# ...
"primary_sidebar_end": ["sidebar-ethical-ads"],
# ...
}
``sidebar-ethical-ads.html`` is a placement for ReadTheDocs's Ethical Ads (will only show up on ReadTheDocs).
Remove the primary sidebar from pages
-------------------------------------
If you'd like the primary sidebar to be removed from a page, you can use the
following configuration in ``conf.py``:
.. code-block:: python
html_sidebars = {
"pagename": []
}
This works for glob-style patterns as well. For example:
.. code-block:: python
html_sidebars = {
"folder/*": []
}
If you'd like to remove the primary sidebar from **all** pages of your documentation,
use this pattern:
.. code-block:: python
html_sidebars = {
"**": []
}
.. _layout-footer-content:
Footer Content
==============
Located in ``sections/footer-content.html``.
The footer content is a narrow bar spanning the article's content and the 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.
.. _layout-sidebar-secondary:
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']``.
By default, it has the following templates:
.. code-block:: python
html_theme_options = {
# ...
"secondary_sidebar_items": ["page-toc", "edit-this-page", "sourcelink"],
# ...
}
To learn how to further customize or remove the secondary sidebar, please check :doc:`page-toc`.
.. _layout-article-footer:
Article Footer
==============
Located in ``sections/footer-article.html``.
The article footer exists just below your page's article. By default, It does not contain anything immediately viewable to the reader, but is kept as a placeholder for custom or built-in templates.
.. code-block:: python
html_theme_options = {
# ...
"article_footer_items": [],
# ...
}
Hide the previous and next buttons
----------------------------------
By default, each page of your site will have "previous" and "next" buttons
at the bottom displayed in the ``prev_next_area``. You can hide these buttons with the following configuration:
.. code:: python
html_theme_options = {
"show_prev_next": False
}
Content Footer
==============
Located in ``sections/footer-content.html``.
The content footer exists below your page's article and secondary sidebar.
By default it is empty, but you can add templates to it with the following configuration:
.. code-block:: python
html_theme_options = {
# ...
"content_footer_items": ["your-template.html"],
# ...
}
.. _layout-footer:
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_start']``, ``html_theme_options['footer_center']`` and ``html_theme_options['footer_end']``.
By default, ``footer_center`` is empty, and ``footer_start`` and ``footer_end`` have the following templates:
.. code-block:: python
html_theme_options = {
#...
"footer_start": ["copyright", "sphinx-version"],
"footer_end": ["theme-version"]
#...
}
Within each subsection, components will stack **vertically**.
If you'd like them to stack **horizontally** use a custom CSS rule like the following:
.. code-block:: css
.footer-items__start, .footer-items__end {
flex-direction: row;
}
Built-in components to insert into sections
===========================================
Below is a list of built-in templates that you can insert into any section.
Note that some of them may have CSS rules that assume a specific section (and
will be named accordingly).
.. note::
When adding/changing/overwritting a component, the ".html" suffix is optional.
That's why all of them are displayed without it in the following list.
.. component-list::
Add your own HTML templates to theme sections
=============================================
If you'd like to add your own custom template to any of these sections, you
could do so with the following steps:
1. Create an HTML file in a folder called ``_templates``. For example, if
you wanted to display the version of your documentation using a Jinja
template, you could create a file: ``_templates/version.html`` and put the
following in it:
.. code-block:: html
{{ version }}
2. Now add the file to your menu items for one of the sections above. For example:
.. code-block:: python
html_theme_options = {
# ...
"navbar_start": ["navbar-logo", "version"],
# ...
}
Build date
==========
By default this theme does not display the build date even when Sphinx's `html_last_updated_fmt `__ variable is set. If you want the build date displayed, the theme includes a :code:`last-updated` template that you can add to one of the page regions in your ``conf.py``. For example:
.. code-block:: python
:caption: conf.py
html_theme_options = {
"content_footer_items": ["last-updated"],
# other settings...
}
If you do specify ``html_last_updated_fmt`` but don't include the :code:`last-updated` template, the theme will still write the build date into a ``meta`` tag in the HTML header, which can be inspected by viewing the page source or extracted with an HTML parser. The tag will look like:
.. code-block:: html
The tag's ``content`` attribute will follow the format specified in the ``html_last_updated_fmt`` configuration variable.
.. _references:
References
==========
Please find here the full list of keys you can use in the ``html_theme_options`` in ``conf.py``:
.. include:: ../../src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf
:code: ini
:class: highlight-ini