kaxil opened a new issue, #1344: URL: https://github.com/apache/airflow-site/issues/1344
## Problem Code blocks in Sphinx documentation have incorrect syntax highlighting colors: - Keywords (`import`) and module names (`pendulum`) render with the same color in both light and dark modes - Light mode: both blue - Dark mode: both red, with poor contrast <img width="1124" height="467" alt="Image" src="https://github.com/user-attachments/assets/3b3b0d25-b672-4986-9445-e6b09b7e7b8e"; /> (Example from https://airflow.apache.org/docs/apache-airflow/stable/index.html) **Expected:** Different token types should have distinct colors, similar to VS Code or GitHub's actual syntax highlighting. **NOTE**: THIS IS NOT AN ISSUE WITH HUGO & DOCSY'S BLOG, EXAMPLE: <img width="850" height="353" alt="Image" src="https://github.com/user-attachments/assets/567325cb-1a36-4c49-89c8-098c0bc66810"; /> ## Root Causes 1. Sphinx was generating its own `pygments.css` that conflicted with custom styles 2. Pygments "github-dark" theme intentionally uses the same color for keywords (`.kn`) and namespaces (`.nn`), but GitHub's actual website differentiates them 3. Hardcoded gray color in `pre span` fallback prevented theme-aware colors ## Potential Solutions 1. **`landing-pages/site/assets/scss/_highlights.scss`** - Changed`pre span` to use `color: var(--bs-body-color)` instead of hardcoded gray for theme-aware fallback - This allows namespaces to render as white/default in dark mode and black/default in light mode 2. **`landing-pages/site/assets/scss/pygments/_dark.scss`** - Remove explicit `.highlight .nn` rule to allow fallback to theme-aware body color (white/default) - This differentiates namespaces (white) from keywords (red), matching GitHub's actual behavior 3. **`sphinx_airflow_theme/sphinx_airflow_theme/theme.conf`** - Change `pygments_style = default` to `pygments_style = none` - Prevents Sphinx from generating its own `pygments.css` that conflicts with custom styles ## Expected Before/After Examples ### Sphinx Docs (Pygments) **Light Mode:** - **Before:** `import` and `pendulum` both blue - **After:** Keywords distinct from module names **Dark Mode:** - **Before:** `import` and `pendulum` both red, poor contrast - **After:** Keywords (red), module names (white/default), better contrast ## Technical Details - **Pygments**: Used for Sphinx documentation code blocks - **Theme-aware colors**: Used `var(--bs-body-color)` for fallback colors that adapt to light/dark mode - **GitHub-dark customization**: Removed `.nn` override to allow namespaces to use default body color instead of matching keywords -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
