feat: Allow customizing emphasis and bold text colors via html_theme_options

[mmcky]

Summary

Resolves #355 — Allow customizing emphasis, bold/strong, and definition text colors via html_theme_options.

Adds six new theme options that let users override the default colors for emphasis (italic), bold/strong, and definition list terms in both light and dark modes, using CSS custom properties with graceful fallbacks.

New Theme Options

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

Usage

Sphinx conf.py:

html_theme_options = {
    "emphasis_color": "#1a73e8",
    "emphasis_color_dark": "#8ab4f8",
    "strong_color": "#d93025",
    "strong_color_dark": "#f28b82",
    "definition_color": "#6a1b9a",
    "definition_color_dark": "#ce93d8",
}

Jupyter Book _config.yml:

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"

Any option left empty uses the theme's built-in default. The definition_color options target Sphinx definition lists (dl.simple, dl.glossary, dl.field-list), while strong_color applies to all inline strong/b text. Definitions fall back to the strong color by default via CSS variable chain.

Implementation

• SCSS: CSS custom properties (--qe-emphasis-color, --qe-strong-color, --qe-definition-color) with SCSS fallback values in _base.scss and _dark-theme.scss
• Theme config: Six new options registered in theme.conf (all default to empty)
• Template: layout.html conditionally injects <style> block with CSS variable overrides on :root and body.dark-theme
• Tests: 40 tests covering theme options, SCSS variables, compiled CSS output, and template injection
• Docs: Updated configure.md with usage examples, Jupyter Book config, and option reference table

Testing

All 40 custom color tests pass, plus existing test suite (65 total tests pass).

[codecov]

Codecov Report

❌ Patch coverage is 90.90909% with 1 line in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (main@c25b251). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
src/quantecon_book_theme/__init__.py	90.90%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #356   +/-   ##
=======================================
  Coverage        ?   46.48%           
=======================================
  Files           ?        2           
  Lines           ?      398           
  Branches        ?        0           
=======================================
  Hits            ?      185           
  Misses          ?      213           
  Partials        ?        0           

Flag	Coverage Δ
pytests	46.48% <90.90%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

🎭 Visual Regression Test Results

 45 passed
 1 skipped

Details

 46 tests across 1 suite
 58 seconds
 c88b659

Skipped tests

mobile-chrome › theme.spec.ts › Theme Features › f-string interpolation styling

[github-actions]

🚀 Deployed on https://69856bf93c328a45272ee100--hungry-lovelace-7d0512.netlify.app

[mmcky]

/update-new-snapshots

[mmcky]

/update-new-snapshots

[github-actions]

✅ Visual snapshots have been updated and committed to this PR.

[Copilot]

Pull request overview

This pull request implements a feature to allow customization of emphasis (italic), bold/strong, and definition text colors through html_theme_options, resolving issue #355. The implementation uses CSS custom properties with graceful fallbacks to SCSS-defined default colors, allowing users to override text styling colors without needing custom CSS files.

Changes:

• Added six new theme options (emphasis_color, emphasis_color_dark, strong_color, strong_color_dark, definition_color, definition_color_dark) for customizing text colors in light and dark modes
• Implemented CSS variable injection in layout.html to apply user-specified colors via :root and body.dark-theme selectors
• Updated SCSS files (_base.scss and _dark-theme.scss) to use CSS custom properties with fallback values for backward compatibility
• Added comprehensive test coverage (40 tests) covering theme configuration, SCSS variables, compiled CSS, and template injection
• Added visual regression tests for typography styling in both light and dark modes
• Updated documentation with usage examples for both Sphinx and Jupyter Book configurations
• Enhanced developer documentation (.github/copilot-instructions.md) with GitHub CLI best practices

Reviewed changes

Copilot reviewed 8 out of 16 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/quantecon_book_theme/theme/quantecon_book_theme/theme.conf	Registers six new color customization options with empty defaults
src/quantecon_book_theme/theme/quantecon_book_theme/layout.html	Conditionally injects CSS custom property overrides when theme options are set
src/quantecon_book_theme/assets/styles/_base.scss	Updates em, strong/b, and dl dt selectors to use CSS variables with SCSS fallbacks
src/quantecon_book_theme/assets/styles/_dark-theme.scss	Updates dark mode colors to use CSS variables with fallbacks
tests/test_custom_colors.py	Adds 40 tests verifying theme options, SCSS variables, compiled CSS, and template injection
tests/visual/theme.spec.ts	Adds visual regression tests for bold and italic text in light and dark modes
tests/visual/__snapshots__/**/*.png	Visual test baseline snapshots for typography styling
docs/configure.md	Documents the new color customization options with usage examples and reference table
.github/copilot-instructions.md	Adds GitHub CLI best practices for avoiding shell escaping issues

[mmcky]

Addressing Copilot Review Feedback

Thanks for the review. Both comments have been addressed in commit f77e6a1:

1. CSS Injection Vulnerability (layout.html)

Rather than the suggested |e filter approach (which would quote the values and break CSS custom properties), I added server-side validation in __init__.py. A validate_color_options() function runs at builder-inited time and checks all 6 color options against a regex that allows only safe CSS color patterns:

• Hex codes: #RGB, #RRGGBB, #RRGGBBAA
• Named colors: red, DarkSlateGray, etc.
• Functions: rgb(), rgba(), hsl(), hsla()
• CSS variables: var(--custom-prop)

Invalid values (e.g. red; } body { display: none; } /*) are replaced with empty strings and a Sphinx warning is logged.

2. Security Note in Documentation (configure.md)

Added a {note} admonition explaining that color values are validated at build time and should only come from trusted configuration files.

Tests

Added 14 new tests in TestColorValueValidation covering both valid color formats and malicious injection patterns (semicolons, braces, url(), expression()). Total: 54 tests passing.