Make sticky_contents default to True (#371)

* Make sticky_contents default to True

The sticky right-hand table of contents with scroll spy was introduced
in 0.17.0 and has proven to be the preferred experience. This change
enables it by default for all projects using the theme.

Users can opt out by setting sticky_contents: false in html_theme_options.

* Address Copilot review feedback

- test: assert back-to-top and data-autoexpand absent when sticky disabled
- docs: note contents_autoexpand only affects sticky TOC
- changelog: clarify opt-out for both Python conf.py and YAML _config.yml

Author: mmcky

CHANGELOG.md

@@ -5,6 +5,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Changed
+- **`sticky_contents` now defaults to `True`** — the sticky right-hand table of contents with scroll spy is now enabled by default for all projects using the theme. To revert to the classic TOC, set `sticky_contents: False` in `html_theme_options` in `conf.py`, or `sticky_contents: false` in YAML-based configuration (e.g. `_config.yml`).
+
 ## [0.18.0] - 2026-02-24
 
 ### Changed

docs/user/configuration.md

@@ -149,12 +149,25 @@ filter to the site logo.
 
 ## Sticky Table of Contents
 
-Enable a fixed right-hand table of contents with scroll spy and auto-expansion:
+The theme includes a fixed right-hand table of contents with scroll spy and
+auto-expansion, enabled by default.
+
+### Features
+
+- **Fixed positioning** — the TOC stays visible while scrolling
+- **Active section highlighting** — the current section is highlighted
+- **Copy section link** — hover over a TOC entry to reveal a copy icon
+- **Back to top button** — appears after scrolling down 300px
+- **Auto-expand subsections** — subsections expand as you scroll
+
+### Disable sticky TOC
+
+To revert to the classic (non-sticky) table of contents:
 
 ```python
 html_theme_options = {
     ...
-    "sticky_contents": True,
+    "sticky_contents": False,
     ...
 }
 ```
@@ -165,30 +178,20 @@ For Jupyter Book projects:
 sphinx:
   config:
     html_theme_options:
-      sticky_contents: true
+      sticky_contents: false
 ```
 
-### Features
-
-When enabled:
-- **Fixed positioning** — the TOC stays visible while scrolling
-- **Active section highlighting** — the current section is highlighted
-- **Copy section link** — hover over a TOC entry to reveal a copy icon
-- **Back to top button** — appears after scrolling down 300px
-- **Auto-expand subsections** — subsections expand as you scroll
-
 ### Disable auto-expansion
 
 ```python
 html_theme_options = {
     ...
-    "sticky_contents": True,
     "contents_autoexpand": False,
     ...
 }
 ```
 
-When `contents_autoexpand` is `False`, only top-level section names are displayed.
+When `contents_autoexpand` is `False`, only top-level section names are displayed. Note that this option only has an effect when the sticky TOC is enabled (the default); it has no impact when `sticky_contents` is set to `False`.
 
 ## Customizing Toggle Buttons
 

src/quantecon_book_theme/theme/quantecon_book_theme/theme.conf

@@ -31,7 +31,7 @@ path_to_docs =
 persistent_sidebar = False
 plugins_list = []
 quantecon_project = True
-sticky_contents = False
+sticky_contents = True
 repository_branch =
 repository_url =
 single_page = False

tests/test_build.py

@@ -428,30 +428,36 @@ def test_sticky_toc(sphinx_build):
     """Test that sticky_contents and contents_autoexpand options work correctly."""
     sphinx_build.copy()
 
-    # Test default behavior - sticky TOC should be disabled
+    # Test default behavior - sticky TOC should be enabled by default
     sphinx_build.build()
     index_html = sphinx_build.get("index.html")
     toc_inner = index_html.find("div", class_="inner")
-    # By default, sticky class should NOT be present
-    assert toc_inner is None or "sticky" not in toc_inner.get("class", [])
+    # By default, sticky class should be present
+    assert toc_inner is not None
+    assert "sticky" in toc_inner.get("class", [])
+    # Default contents_autoexpand should be True
+    assert toc_inner.get("data-autoexpand") == "true"
+    # Back to top button should be present
+    back_to_top = index_html.find("a", class_="back-to-top-btn")
+    assert back_to_top is not None
     sphinx_build.clean()
 
-    # Test with sticky_contents enabled
+    # Test with sticky_contents explicitly disabled
     cmd = [
         "-D",
-        "html_theme_options.sticky_contents=True",
+        "html_theme_options.sticky_contents=False",
     ]
     sphinx_build.build(cmd)
     index_html = sphinx_build.get("index.html")
     toc_inner = index_html.find("div", class_="inner")
-    # When enabled, sticky class should be present
-    assert toc_inner is not None
-    assert "sticky" in toc_inner.get("class", [])
-    # Default contents_autoexpand should be True
-    assert toc_inner.get("data-autoexpand") == "true"
-    # Back to top button should be present
+    # When disabled, sticky class should NOT be present
+    assert toc_inner is None or "sticky" not in toc_inner.get("class", [])
+    # Back to top button should NOT be present when sticky contents are disabled
     back_to_top = index_html.find("a", class_="back-to-top-btn")
-    assert back_to_top is not None
+    assert back_to_top is None
+    # data-autoexpand attribute should NOT be present when sticky contents are disabled
+    if toc_inner is not None:
+        assert toc_inner.get("data-autoexpand") is None
     sphinx_build.clean()
 
     # Test with sticky_contents enabled and contents_autoexpand disabled