Add style_solution_after_exercise config option and improve dropdown UX

This commit adds two requested features for better solution styling:

1. New configuration option 'style_solution_after_exercise' (default: False)
   - When enabled, removes hyperlinks from solution titles
   - Displays plain text like 'Solution to Exercise 1 (Title)'
   - Useful when solutions follow exercises directly
   - Reduces confusion when using dropdown class

2. Improved dropdown button text
   - Changed 'Click to show' to 'Show' for cleaner UI
   - Changed 'Click to hide' to 'Hide'
   - Applied via CSS customization

Features:
- Backward compatible (opt-in configuration)
- Properly handles numbered/unnumbered exercises
- Supports math expressions in titles
- Comprehensive test coverage (3 new tests)
- Full documentation in syntax.md

All 113 tests pass.

Author: mmcky

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+### New ✨
+
+- Added `style_solution_after_exercise` configuration option to remove hyperlinks from solution titles when solutions follow exercises directly
+- Changed dropdown button text from "Click to show" to "Show" for cleaner visual appearance
+
+### Improved 👌
+
+- Enhanced solution title styling options for better UX in lecture-style content where solutions follow exercises
+
 ## [v1.1.1](https://github.com/executablebooks/sphinx-exercise/tree/v1.1.1) (2025-10-23)
 
 ### Improved 👌

docs/source/syntax.md

@@ -343,6 +343,8 @@ sphinx:
 
 To hide the content, simply add `:class: dropdown` as a directive option.
 
+**Note:** The dropdown toggle button text has been customized for `sphinx-exercise` directives to display "Show" / "Hide" instead of the default "Click to show" / "Click to hide" for a cleaner visual appearance.
+
 For more use cases see [sphinx-togglebutton](https://sphinx-togglebutton.readthedocs.io/en/latest/#usage).
 
 **Example**
@@ -407,6 +409,31 @@ sphinx:
 ...
 ```
 
+### Solution Title Styling
+
+By default, solution titles include a hyperlink to the corresponding exercise. This behavior can be modified using the `style_solution_after_exercise` configuration option.
+
+When solutions follow exercises directly in your content (common in lecture notes), you may want to remove the hyperlink to avoid confusion when using the `dropdown` class. Set `style_solution_after_exercise` to `True` to display only text without hyperlinks in solution titles.
+
+For Sphinx projects, add the configuration key in the `conf.py` file:
+
+```python
+# conf.py
+style_solution_after_exercise = True
+```
+
+For Jupyter Book projects, set the configuration key in `_config.yml`:
+
+```yaml
+...
+sphinx:
+  config:
+    style_solution_after_exercise: True
+...
+```
+
+When `style_solution_after_exercise` is `True`, the solution title will display plain text like "Solution to Exercise 1 (Title)" instead of a hyperlink. When `False` (default), the exercise reference in the solution title remains clickable.
+
 ## Custom CSS or JavaScript
 
 Custom JavaScript scripts and CSS rules will allow you to add additional functionality or customize how elements are displayed. If you'd like to include custom CSS or JavaScript scripts in Jupyter Book, simply add any files ending in `.css` or `.js` under a `_static` folder. Any files under this folder will be automatically copied into the built book.

sphinx_exercise/__init__.py

@@ -147,6 +147,7 @@ def doctree_read(app: Sphinx, document: Node) -> None:
 
 def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_config_value("hide_solutions", False, "env")
+    app.add_config_value("style_solution_after_exercise", False, "env")
 
     app.connect("config-inited", init_numfig)  # event order - 1
     app.connect("env-purge-doc", purge_exercises)  # event order - 5 per file

sphinx_exercise/assets/html/exercise.css

@@ -41,3 +41,17 @@ div.solution p.admonition-title {
 div.solution p.admonition-title::after {
   content: none;
 }
+
+/*********************************************
+* Dropdown customization *
+*********************************************/
+/* Change "Click to show" to "Show" for dropdowns */
+div.exercise.dropdown button.toggle-button::before,
+div.solution.dropdown button.toggle-button::before {
+  content: "Show";
+}
+
+div.exercise.dropdown.toggle-shown button.toggle-button::before,
+div.solution.dropdown.toggle-shown button.toggle-button::before {
+  content: "Hide";
+}

sphinx_exercise/post_transforms.py

@@ -147,24 +147,49 @@ def resolve_solution_title(app, node, exercise_node):
             updated_title_text += f" {node_number}"
         # New Title Node
         updated_title = docutil_nodes.title()
-        wrap_reference = build_reference_node(app, exercise_node)
-        wrap_reference += docutil_nodes.Text(updated_title_text)
-        node["title"] = entry_title_text + updated_title_text
-        # Parse Custom Titles from Exercise
-        if len(exercise_title.children) > 1:
-            subtitle = exercise_title.children[1]
-            if isinstance(subtitle, exercise_subtitle):
-                wrap_reference += docutil_nodes.Text(" (")
-                for child in subtitle.children:
-                    if isinstance(child, docutil_nodes.math):
-                        # Ensure mathjax is loaded for pages that only contain
-                        # references to nodes that contain math
-                        domain = app.env.get_domain("math")
-                        domain.data["has_equations"][app.env.docname] = True
-                    wrap_reference += child
-                wrap_reference += docutil_nodes.Text(")")
-        updated_title += docutil_nodes.Text(entry_title_text)
-        updated_title += wrap_reference
+
+        # Check if style_solution_after_exercise is enabled
+        if app.config.style_solution_after_exercise:
+            # Don't create hyperlink - just add plain text and nodes
+            updated_title += docutil_nodes.Text(entry_title_text)
+            updated_title += docutil_nodes.Text(updated_title_text)
+            node["title"] = entry_title_text + updated_title_text
+
+            # Parse Custom Titles from Exercise
+            if len(exercise_title.children) > 1:
+                subtitle = exercise_title.children[1]
+                if isinstance(subtitle, exercise_subtitle):
+                    updated_title += docutil_nodes.Text(" (")
+                    for child in subtitle.children:
+                        if isinstance(child, docutil_nodes.math):
+                            # Ensure mathjax is loaded for pages that only contain
+                            # references to nodes that contain math
+                            domain = app.env.get_domain("math")
+                            domain.data["has_equations"][app.env.docname] = True
+                        # Add child directly (could be text or math node)
+                        updated_title += child.deepcopy()
+                    updated_title += docutil_nodes.Text(")")
+        else:
+            # Create hyperlink (original behavior)
+            wrap_reference = build_reference_node(app, exercise_node)
+            wrap_reference += docutil_nodes.Text(updated_title_text)
+            node["title"] = entry_title_text + updated_title_text
+            # Parse Custom Titles from Exercise
+            if len(exercise_title.children) > 1:
+                subtitle = exercise_title.children[1]
+                if isinstance(subtitle, exercise_subtitle):
+                    wrap_reference += docutil_nodes.Text(" (")
+                    for child in subtitle.children:
+                        if isinstance(child, docutil_nodes.math):
+                            # Ensure mathjax is loaded for pages that only contain
+                            # references to nodes that contain math
+                            domain = app.env.get_domain("math")
+                            domain.data["has_equations"][app.env.docname] = True
+                        wrap_reference += child
+                    wrap_reference += docutil_nodes.Text(")")
+            updated_title += docutil_nodes.Text(entry_title_text)
+            updated_title += wrap_reference
+
         updated_title.parent = title.parent
         node.children[0] = updated_title
     node.resolved_title = True

tests/test_style_solution_after_exercise.py

@@ -0,0 +1,97 @@
+from bs4 import BeautifulSoup
+import pytest
+import sphinx
+
+# Sphinx 8.1.x (Python 3.10 only) has different XML output than 8.2+
+# Use .sphinx8.1 for 8.1.x, .sphinx8 for 8.2+ (the standard)
+if sphinx.version_info[0] == 8 and sphinx.version_info[1] == 1:
+    SPHINX_VERSION = f".sphinx{sphinx.version_info[0]}.{sphinx.version_info[1]}"
+else:
+    SPHINX_VERSION = f".sphinx{sphinx.version_info[0]}"
+
+
+@pytest.mark.sphinx(
+    "html", testroot="mybook", confoverrides={"style_solution_after_exercise": True}
+)
+def test_solution_no_link(app):
+    """Test solution directive with style_solution_after_exercise=True removes hyperlink."""
+    app.build()
+    path_solution_directive = app.outdir / "solution" / "_linked_enum.html"
+    assert path_solution_directive.exists()
+
+    # get content markup
+    soup = BeautifulSoup(
+        path_solution_directive.read_text(encoding="utf8"), "html.parser"
+    )
+
+    sol = soup.select("div.solution")[0]
+    title = sol.select("p.admonition-title")[0]
+
+    # Check that there is NO hyperlink in the title when style_solution_after_exercise=True
+    links = title.find_all("a")
+    assert (
+        len(links) == 0
+    ), "Solution title should not contain hyperlink when style_solution_after_exercise=True"
+
+    # Check that the title text still contains the exercise reference
+    title_text = title.get_text()
+    assert "Exercise" in title_text
+    assert "This is a title" in title_text
+
+
+@pytest.mark.sphinx(
+    "html", testroot="mybook", confoverrides={"style_solution_after_exercise": False}
+)
+def test_solution_with_link(app):
+    """Test solution directive with style_solution_after_exercise=False keeps hyperlink."""
+    app.build()
+    path_solution_directive = app.outdir / "solution" / "_linked_enum.html"
+    assert path_solution_directive.exists()
+
+    # get content markup
+    soup = BeautifulSoup(
+        path_solution_directive.read_text(encoding="utf8"), "html.parser"
+    )
+
+    sol = soup.select("div.solution")[0]
+    title = sol.select("p.admonition-title")[0]
+
+    # Check that there IS a hyperlink in the title when style_solution_after_exercise=False (default)
+    links = title.find_all("a")
+    assert (
+        len(links) == 1
+    ), "Solution title should contain hyperlink when style_solution_after_exercise=False"
+
+    # Check that the link points to the exercise
+    link = links[0]
+    assert "href" in link.attrs
+    assert "ex-number" in link["href"]
+
+
+@pytest.mark.sphinx(
+    "html", testroot="mybook", confoverrides={"style_solution_after_exercise": True}
+)
+def test_solution_no_link_unenum(app):
+    """Test unnumbered solution directive with style_solution_after_exercise=True removes hyperlink."""
+    app.build()
+    path_solution_directive = app.outdir / "solution" / "_linked_unenum_title.html"
+    assert path_solution_directive.exists()
+
+    # get content markup
+    soup = BeautifulSoup(
+        path_solution_directive.read_text(encoding="utf8"), "html.parser"
+    )
+
+    sol = soup.select("div.solution")[0]
+    title = sol.select("p.admonition-title")[0]
+
+    # Check that there is NO hyperlink in the title
+    links = title.find_all("a")
+    assert (
+        len(links) == 0
+    ), "Solution title should not contain hyperlink when style_solution_after_exercise=True"
+
+    # Check that the title text still contains the exercise reference
+    title_text = title.get_text()
+    assert "Exercise" in title_text
+    assert "This is a title" in title_text