Fix Syntax Highlighting in Code Blocks (Sphinx Docs)

[kaxil]

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

(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:

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

   • Changedpre 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: Use var(--bs-body-color) for fallback colors that adapt to light/dark mode

[kaxil]

cc @SHASHI9705

[SHASHI9705]

Hi @kaxil , apologies for the delay,I was tied up with my exams. Thanks for the mention. I’ve started looking into this and will share an update soon.

[kaxil]

Hi @kaxil , apologies for the delay,I was tied up with my exams. Thanks for the mention. I’ve started looking into this and will share an update soon.

Awesome