feat: Allow customizing emphasis and bold text colors via html_theme_options (#356)

* feat: Allow customizing emphasis and bold text colors via html_theme_options

Add four new theme options to customize emphasis (em) and definition
(strong/b) text colors for both light and dark modes:

- emphasis_color: Color for em tags in light mode (default: #2d9f42)
- emphasis_color_dark: Color for em tags in dark mode (default: #66bb6a)
- definition_color: Color for strong/b tags in light mode (default: #8b4513)
- definition_color_dark: Color for strong/b tags in dark mode (default: #cd853f)

Implementation approach:
- Replace hardcoded SCSS colors with CSS custom properties (var())
  with fallback values matching the original defaults
- Register new options in theme.conf with empty defaults
- Inject custom property overrides via inline style in layout.html
  when theme options are set

This is fully backward-compatible: existing sites see no visual change.
When options are left empty, CSS var() fallbacks provide the original colors.

Closes #355

* refactor: rename definition_color to strong_color for accuracy

The option applies to all <strong>/<b> elements, not just definitions.
Sphinx renders actual definitions via <dl>/<dt> elements which can be
targeted separately. Renamed across SCSS, theme.conf, layout.html,
tests, and documentation.

* Add definition_color option targeting Sphinx definition list terms

Add definition_color and definition_color_dark theme options that
target actual Sphinx definition list elements (dl.simple dt,
dl.glossary dt, dl.field-list dt) separately from strong/bold text.

The definition color falls back to the strong color via CSS variable
chain: var(--qe-definition-color, var(--qe-strong-color, fallback)),
so definitions inherit from strong_color by default but can be
independently customized.

* Fix black formatting in test_custom_colors.py

* Add visual regression tests for bold and italic typography

Add 5 Playwright visual tests in a new 'Typography Styling' describe block:
- bold text styling (light mode)
- italic text styling (light mode)
- mixed bold and italic styling
- bold text in dark mode
- italic text in dark mode

Uses .qe-page__content selectors to target paragraphs containing
<strong> and <em> elements on names.html, numpy.html, and
python_by_example.html.

Note: definition list (<dl>) tests not included as the lecture site
does not currently contain definition lists.

* UPDATE: Visual regression snapshots [skip ci]

* Remove fragile mixed bold/italic visual test and snapshot

* Add CSS color value validation to prevent injection

- Validate color theme options against safe CSS patterns (hex, named colors,
  rgb/hsl functions) at build time
- Invalid values are ignored with a warning logged
- Add 14 tests for validation regex (valid and malicious patterns)
- Add security note to documentation

Addresses Copilot code review feedback on PR #356.

* Add unit tests for validate_color_options to improve patch coverage

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: mmcky

.github/copilot-instructions.md

@@ -92,6 +92,13 @@ src/quantecon_book_theme/
 - **Alternative**: Try `pip install --timeout=120` for longer timeout
 
 ### GitHub CLI (gh) Issues
+- **Shell Escaping**: zsh has many issues with shell escaping, heredocs, and multiline strings. **ALWAYS** use the `create_file` tool to write content to a temporary file first, then pass it to `gh` with the `--body-file` flag. **NEVER** pass multiline body content directly via `--body` in the terminal.
+  - Example workflow for updating a PR description:
+    1. Use `create_file` to write the body to `/tmp/pr_body.md`
+    2. Run: `gh pr edit 123 --body-file /tmp/pr_body.md`
+  - Example workflow for creating a release:
+    1. Use `create_file` to write release notes to `/tmp/release_notes.md`
+    2. Run: `gh release create vX.Y.Z --title "Title" --notes-file /tmp/release_notes.md`
 - **Output Capture**: Always write gh output to `/tmp` file for reliable capture: `gh pr view 123 2>&1 | tee /tmp/gh_output.txt`
 
 ### Missing Python 3.13
@@ -240,12 +247,14 @@ git push && git push origin vX.Y.Z
 
 ### 5. Create GitHub Release
 ```bash
+# Write release notes to a temp file first (use create_file tool)
+# Then create the release using --notes-file
 gh release create vX.Y.Z \
   --title "vX.Y.Z - Release Title" \
-  --notes "Release notes from CHANGELOG.md"
+  --notes-file /tmp/release_notes.md
 ```
 
-**IMPORTANT**: Creating the GitHub release triggers the PyPI publish workflow automatically.
+**IMPORTANT**: Always use `--notes-file` with a temp file instead of `--notes` to avoid zsh shell escaping issues. Creating the GitHub release triggers the PyPI publish workflow automatically.
 
 ### 6. Verify PyPI Publication
 - Check GitHub Actions for successful PyPI publish workflow

docs/configure.md

@@ -323,3 +323,60 @@ This is a collapsible note that will show "Show" when collapsed and "Hide" when
 ```{toggle}
 This is a toggle directive that will use the configured button text.
 ```
+
+## Customizing Emphasis and Definition Colors
+
+The theme applies custom colors to emphasis (italic), bold/strong, and definition list terms. By default:
+
+- **Emphasis** (`em`): Green (`#2d9f42`) in light mode, lighter green (`#66bb6a`) in dark mode
+- **Bold/Strong** (`strong`, `b`): Brown (`#8b4513`) in light mode, lighter brown (`#cd853f`) in dark mode
+- **Definitions** (`dl dt`): Inherits from bold/strong color by default
+
+You can override these colors using `html_theme_options`:
+
+```python
+html_theme_options = {
+    ...
+    "emphasis_color": "#1a73e8",
+    "emphasis_color_dark": "#8ab4f8",
+    "strong_color": "#d93025",
+    "strong_color_dark": "#f28b82",
+    "definition_color": "#6a1b9a",
+    "definition_color_dark": "#ce93d8",
+    ...
+}
+```
+
+For Jupyter Book projects, add to your `_config.yml`:
+
+```yaml
+sphinx:
+  config:
+    html_theme_options:
+      emphasis_color: "#1a73e8"
+      emphasis_color_dark: "#8ab4f8"
+      strong_color: "#d93025"
+      strong_color_dark: "#f28b82"
+      definition_color: "#6a1b9a"
+      definition_color_dark: "#ce93d8"
+```
+
+| Option | Description | Default |
+|---|---|---|
+| `emphasis_color` | Color for `em` tags in light mode | `#2d9f42` (green) |
+| `emphasis_color_dark` | Color for `em` tags in dark mode | `#66bb6a` (light green) |
+| `strong_color` | Color for `strong`/`b` tags in light mode | `#8b4513` (brown) |
+| `strong_color_dark` | Color for `strong`/`b` tags in dark mode | `#cd853f` (peru) |
+| `definition_color` | Color for definition list terms (`dl dt`) in light mode | Inherits from `strong_color` |
+| `definition_color_dark` | Color for definition list terms (`dl dt`) in dark mode | Inherits from `strong_color_dark` |
+
+Any option left empty will use the theme's built-in default color. The `definition_color`
+options target Sphinx definition lists, glossary terms, and field lists specifically,
+while `strong_color` applies to all inline bold/strong text.
+
+```{note}
+Color values are validated at build time against safe CSS color patterns
+(hex codes, named colors, `rgb()`/`hsl()` functions). Invalid values are
+ignored and a warning is logged. Only use trusted color values from your
+own configuration files.
+```

src/quantecon_book_theme/__init__.py

@@ -3,6 +3,7 @@
 from pathlib import Path
 import os
 import hashlib
+import re
 from functools import lru_cache
 import subprocess
 from datetime import datetime, timezone
@@ -594,6 +595,48 @@ def _string_or_bool(var):
         return var is None
 
 
+# Valid CSS color pattern: hex (#RGB, #RRGGBB, #RRGGBBAA), named colors,
+# rgb/rgba/hsl/hsla functions, or CSS keywords
+_CSS_COLOR_RE = re.compile(
+    r"^("
+    r"#[0-9a-fA-F]{3,8}"
+    r"|[a-zA-Z]+"
+    r"|rgba?\([^)]+\)"
+    r"|hsla?\([^)]+\)"
+    r"|var\(--[a-zA-Z0-9-]+\)"
+    r")$"
+)
+
+_COLOR_OPTIONS = [
+    "emphasis_color",
+    "emphasis_color_dark",
+    "strong_color",
+    "strong_color_dark",
+    "definition_color",
+    "definition_color_dark",
+]
+
+
+def validate_color_options(app):
+    """Validate that color theme options contain safe CSS color values.
+
+    Prevents CSS injection by ensuring color values match a known-safe pattern
+    (hex colors, named colors, rgb/hsl functions). Invalid values are replaced
+    with empty strings and a warning is logged.
+    """
+    theme_options = app.config.html_theme_options
+    for option in _COLOR_OPTIONS:
+        value = theme_options.get(option, "")
+        if value and not _CSS_COLOR_RE.match(value.strip()):
+            SPHINX_LOGGER.warning(
+                "Ignoring invalid CSS color value for %s: %r. "
+                "Use hex (#RRGGBB), named colors, or rgb()/hsl() functions.",
+                option,
+                value,
+            )
+            theme_options[option] = ""
+
+
 def setup(app):
     # Configuration for Juypter Book
     app.setup_extension("sphinx_book_theme")
@@ -603,6 +646,7 @@ def setup(app):
 
     app.connect("html-page-context", add_hub_urls)
     app.connect("builder-inited", add_plugins_list)
+    app.connect("builder-inited", validate_color_options)
     app.connect("builder-inited", setup_pygments_css)
     app.connect("html-page-context", hash_html_assets)
     app.connect("html-page-context", add_pygments_style_class)

src/quantecon_book_theme/assets/styles/_base.scss

@@ -151,14 +151,21 @@ h4 {
 em {
   font-style: normal;
   font-weight: 550;
-  color: colors.$emphasis;
+  color: var(--qe-emphasis-color, colors.$emphasis);
 }
 
-// Strong/bold styling - semi-bold weight with color for definitions
+// Strong/bold styling - semi-bold weight with color
 strong,
 b {
   font-weight: 550;
-  color: colors.$definition;
+  color: var(--qe-strong-color, colors.$definition);
+}
+
+// Definition list term styling - inherits from strong color by default
+dl.simple dt,
+dl.glossary dt,
+dl.field-list dt {
+  color: var(--qe-definition-color, var(--qe-strong-color, colors.$definition));
 }
 
 li {

src/quantecon_book_theme/assets/styles/_dark-theme.scss

@@ -23,12 +23,18 @@ body.dark-theme {
 
   // Lighter colors for emphasis and strong in dark mode
   em {
-    color: #66bb6a; // Lighter green for dark mode
+    color: var(--qe-emphasis-color, #66bb6a); // Lighter green for dark mode
   }
 
   strong,
   b {
-    color: #cd853f; // Lighter brown for dark mode
+    color: var(--qe-strong-color, #cd853f); // Lighter brown for dark mode
+  }
+
+  dl.simple dt,
+  dl.glossary dt,
+  dl.field-list dt {
+    color: var(--qe-definition-color, var(--qe-strong-color, #cd853f));
   }
 
   .qe-toolbar__inner > ul > li > a,

src/quantecon_book_theme/theme/quantecon_book_theme/layout.html

@@ -119,6 +119,36 @@
     }
 }
 </style>
+{%- endif %}
+
+<!-- Custom emphasis, strong/bold, and definition colors -->
+{%- if theme_emphasis_color or theme_strong_color or theme_definition_color %}
+<style>
+:root {
+  {%- if theme_emphasis_color %}
+  --qe-emphasis-color: {{ theme_emphasis_color }};
+  {%- endif %}
+  {%- if theme_strong_color %}
+  --qe-strong-color: {{ theme_strong_color }};
+  {%- endif %}
+  {%- if theme_definition_color %}
+  --qe-definition-color: {{ theme_definition_color }};
+  {%- endif %}
+}
+{%- if theme_emphasis_color_dark or theme_strong_color_dark or theme_definition_color_dark %}
+body.dark-theme {
+  {%- if theme_emphasis_color_dark %}
+  --qe-emphasis-color: {{ theme_emphasis_color_dark }};
+  {%- endif %}
+  {%- if theme_strong_color_dark %}
+  --qe-strong-color: {{ theme_strong_color_dark }};
+  {%- endif %}
+  {%- if theme_definition_color_dark %}
+  --qe-definition-color: {{ theme_definition_color_dark }};
+  {%- endif %}
+}
+{%- endif %}
+</style>
 {%- endif %}
 
     <span id="top"></span>

src/quantecon_book_theme/theme/quantecon_book_theme/theme.conf

@@ -36,3 +36,10 @@ twitter =
 twitter_logo_url =
 use_issues_button = False
 use_repository_button = False
+
+emphasis_color =
+emphasis_color_dark =
+strong_color =
+strong_color_dark =
+definition_color =
+definition_color_dark =