diff --git a/docs/conf.py b/docs/conf.py index 99d135133..3e6ed5011 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -65,6 +65,7 @@ "github_url": "https://github.com/pandas-dev/pydata-sphinx-theme", "twitter_url": "https://twitter.com/pandas_dev", "use_edit_page_button": True, + "show_toc_level": 1, } html_context = { diff --git a/docs/user_guide/configuring.rst b/docs/user_guide/configuring.rst index d223872b8..06a1a8a88 100644 --- a/docs/user_guide/configuring.rst +++ b/docs/user_guide/configuring.rst @@ -150,3 +150,22 @@ use the following configuration: html_theme_options = { "navigation_with_keys": False } + + +Show more levels of the in-page TOC by default +============================================== + +Normally only the 2nd-level headers of a page are show in the right +table of contents, and deeper levels are only shown when they are part +of an active section (when it is scrolled on screen). + +You can show deeper levels by default by using the following configuration, indicating how many levels should be displayed: + +.. code-block:: python + + html_theme_options = { + "show_toc_level": 2 + } + +All headings up to and including the level specified will now be shown +regardless of what is displayed on the page. diff --git a/pydata_sphinx_theme/__init__.py b/pydata_sphinx_theme/__init__.py index e7829a5e0..2b60c40a0 100644 --- a/pydata_sphinx_theme/__init__.py +++ b/pydata_sphinx_theme/__init__.py @@ -173,6 +173,9 @@ def get_edit_url(): context["get_edit_url"] = get_edit_url + # Ensure that the max TOC level is an integer + context["theme_show_toc_level"] = int(context.get("theme_show_toc_level", 1)) + # ----------------------------------------------------------------------------- diff --git a/pydata_sphinx_theme/docs-toc.html b/pydata_sphinx_theme/docs-toc.html index 4a6085dab..50f9b1d10 100644 --- a/pydata_sphinx_theme/docs-toc.html +++ b/pydata_sphinx_theme/docs-toc.html @@ -12,7 +12,7 @@
  • {{ item.title }} {%- if item.children -%} -