Skip to content

Upgrade ancient Docsy theme and implement dark mode#1270

Merged
kaxil merged 6 commits intomainfrom
feat-modernize-theme-5qPcf
Dec 17, 2025
Merged

Upgrade ancient Docsy theme and implement dark mode#1270
kaxil merged 6 commits intomainfrom
feat-modernize-theme-5qPcf

Conversation

@kaxil
Copy link
Member

@kaxil kaxil commented Nov 7, 2025

Preview:

This PR upgrades the Docsy theme from v0.2.0-pre (from 2019 !!) to v0.12.0 (latest) and implements Bootstrap 5 dark mode support for both the landing pages and Sphinx documentation. Used https://www.docsy.dev/docs/adding-content/lookandfeel/ and https://www.docsy.dev/docs/updating/ for Upgrading -- it wasn't straight-forward unfortunately but I think I have covered everything that I could find/identify. (including Confetti :D )

Key Changes

  • Theme Upgrade: Docsy v0.2.0-pre → v0.12.0
  • Bootstrap: Upgraded from Bootstrap 4 to Bootstrap 5.3.3
  • Dark Mode: Added theme toggle with light/dark/auto modes

Visual Changes

image image image image image image image image image

Implementation Details

Landing Pages (Hugo/Docsy)

  • Enable showLightDarkModeMenu = true in config.toml
  • Add theme toggle component to navbar (light/dark/auto modes)
  • Store user preference in localStorage
  • Use Bootstrap 5 CSS variables for all UI elements

Sphinx Documentation

  • Add Bootstrap 5 theme toggle to header
  • Style all elements (sidebar, tables, admonitions, forms) for dark mode
  • Use Pygments-generated GitHub Dark theme for syntax highlighting

Technical Requirements

  • Added $td-sidebar-tree-root-color variable (required by Docsy v0.2.0+)
  • Added $font-awesome-font-name variable (required by Docsy v0.6.0+)
  • Added .-bg-orange utility class (required by Docsy v0.6.0+)
  • Created pygments/_dark.scss (generated via: pygmentize -S github-dark)
  • Use hooks/body-end.html for webpack scripts (proper Docsy pattern)

Testing

  • Verified dark mode toggle works on landing pages
  • Confirmed confetti animation adapts to theme changes
  • Tested all admonition types in light and dark modes
  • Verified code syntax highlighting in Sphinx documentation
  • Checked sidebar contrast in dark mode
  • Tested theme persistence across page navigation
  • Verified font consistency (Open Sans) across Hugo and Sphinx pages

@kaxil kaxil mentioned this pull request Nov 7, 2025
2 tasks
@kaxil kaxil force-pushed the feat-modernize-theme-5qPcf branch 6 times, most recently from 2e609f3 to 1624ace Compare November 9, 2025 04:11
@jason810496 jason810496 self-requested a review November 10, 2025 11:54
@kaxil kaxil marked this pull request as ready for review November 10, 2025 18:52
@kaxil
Copy link
Member Author

kaxil commented Dec 15, 2025

Looking at it from fresh eyes:

  • I think the colors on sidebar in dark-mode needs to be more brighter!
  • It should probably match the dark-mode color pallete of Airflow UI -- Maybe!
  • Probably worth splitting it into 2 PRs -- one that's upgrades Docsy (and Hugo) and the other for Dark mode

cc @jason810496 @bbovenzi @pierrejeambrun

Copy link
Member

@jason810496 jason810496 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It should probably match the dark-mode color pallete of Airflow UI

Airflow UI seems to look a bit more "dark blue" style. Anyway, I think it's already good enough for current PR!

It's really nice to see dark mode in official documentation. (Then I don't need to turn on my dark mode reader browser extension when I read the doc directly from Airflow site!)

@dabla
Copy link

dabla commented Dec 15, 2025

Congrats @kaxil and really nice work regarding the dark theme, I think you already mentioned this during the Summit, really like the outcome of this preview, dark mode it is for me already.

@potiuk
Copy link
Member

potiuk commented Dec 15, 2025

Nice! Welcome back @kaxil !

Copy link
Member

@potiuk potiuk left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice. One question - I guess it will not work for historical releases and we will have to likely apply manual css changes to the archive?

@potiuk
Copy link
Member

potiuk commented Dec 15, 2025

We can test it on staging. Just push it as "staging" branch.

Also I've successfully employed Claude Code to bulk apply some vague changes to 100s of thousands of pages in our site-archive when I fixed URLs of downloads, so likely we could do the same if needs be.

We have some docs how to do it in docs/README.md (not the agent but how to push changes to staging from site-archive).

Again - wy might simply get the staging-archive branch and sync it to staging s3.

Copy link
Contributor

@jscheffl jscheffl left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not that I think I can contribute any meaningful review but... cool!

Welcome back!

@choo121600
Copy link
Member

Wow Coool🚀🚀🚀

Copy link
Member

@pierrejeambrun pierrejeambrun left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice 🎉

kaxil added a commit that referenced this pull request Dec 16, 2025
… loading

The homepage was using Docsy's root baseof.html which relied on hooks to load
webpack bundles. However, .Site.Data.webpack was not being populated properly
during the Hugo build for the homepage.

All other sections (blog, docs, community, etc.) have their own baseof.html files
that explicitly load webpack scripts after </body>. This commit adds a root
baseof.html for the homepage using the same pattern.

This matches the approach used in PR #1270 where the confetti animation works
correctly on https://airflow-dark.surge.sh/.
@jscheffl
Copy link
Contributor

jscheffl commented Dec 16, 2025

does #protm actually work on airflow-site as well? :-D

- Fixed corrupted Docsy submodule by removing and re-adding
- Upgraded through major versions: v0.2.0 -> v0.6.0 -> v0.10.0 -> v0.12.0
- Added missing SCSS variables for compatibility:
  * $td-sidebar-tree-root-color
  * $font-awesome-font-name
  * .-bg-orange utility class
- Removed Bootstrap 4 dependencies (switched to Bootstrap 5.3.3)
- Removed custom scripts.html override (conflicts with Bootstrap 5)
- Enabled dark mode via showLightDarkModeMenu = true

Dark mode is now available via the light/dark toggle in the UI.
Upgrade Docsy theme from v0.2.0 to v0.12.0 and implement Bootstrap 5 dark mode.

Core Changes:
- Enable showLightDarkModeMenu in config.toml
- Add theme toggle component to navbar (light/dark/auto modes)
- Store user preference in localStorage
- Respect prefers-color-scheme media query

Styling Implementation:
- Use Bootstrap 5 CSS variables (--bs-body-color, --bs-secondary-bg, etc.) for all UI elements
- Style navbar, header, sidebar, tables, admonitions, and forms for dark mode
- Add Pygments-generated GitHub Dark theme for code syntax highlighting in Sphinx docs
- Adapt confetti animation to dynamically set background based on theme
- Ensure proper semantic colors for all admonition types (note, warning, error, hint, etc.)

Technical Details:
- Added $td-sidebar-tree-root-color variable (required by Docsy v0.2.0+)
- Added $font-awesome-font-name variable (required by Docsy v0.6.0+)
- Added .-bg-orange utility class (required by Docsy v0.6.0+)
- Created pygments/_dark.scss (generated via: pygmentize -S github-dark)
- Use hooks/body-end.html for webpack scripts (proper Docsy pattern)
- Add dark mode support to Sphinx theme (header.html, layout.html)
- Update .gitignore to exclude site/public/ directory

Fixed Issues:
- Confetti animation now visible with transparent header background
- Sidebar links readable in dark mode (increased contrast)
- All admonition types (including seealso) properly colored
- Logo text white in dark mode
- Navbar and header backgrounds adapt to theme

Architecture:
- Removed baseof.html override, use Docsy hooks instead
- Follow Docsy best practices for customization
- Use CSS variables for maintainability

Testing:
- Verified dark mode toggle works on all pages
- Confirmed confetti animation adapts to theme changes
- Tested all admonition types in light and dark modes
- Verified code syntax highlighting in Sphinx documentation

Fix CSS lint errors and add dark mode support for blog page

- Replace hardcoded colors in blog page with Bootstrap CSS variables
- Fix CSS specificity linting errors in rating component
- Add stylelint disable for dark mode block where linter doesn't understand theme context
The Docsy v0.12.0 theme requires Hugo 0.146.0+ and uses Bootstrap/FontAwesome
as NPM dependencies rather than Hugo modules.

Changes:
- Upgraded Hugo from 0.135.0 to 0.146.0 (minimum required by Docsy v0.12.0)
- Added npm install step in Docsy theme directory to install Bootstrap 5.3.6
  and FontAwesome 6.7.2 from theme's package.json

The theme's hugo.yaml mounts these from node_modules/ directories. No Go
installation or Hugo module commands needed.

Tested with act - build completes successfully.
Custom CSS (main-custom.scss) was not being generated after upgrading
Docsy from v0.2.0-pre to v0.12.0.

Root cause:
Docsy v0.12.0 has layouts/_partials/head.html which Hugo prioritizes
over our layouts/partials/head.html, so our CSS processing wasn't called.

Fix:
- Add layouts/_partials/head.html to override Docsy's template
- Add layouts/_partials/head-css.html (must exist in same directory)
- Remove CSS processing from head-end.html hook (moved to head-css.html)
@kaxil kaxil force-pushed the feat-modernize-theme-5qPcf branch from 1624ace to dbcdb6e Compare December 16, 2025 22:31
- Add dark-mode overrides for Docsy/Sphinx left sidebar (CONTENT) toctree links
kaxil added a commit to apache/airflow-site-archive that referenced this pull request Dec 17, 2025
…nges to built apache-airflow stable docs

apache/airflow-site#1270

docs(staging): improve dark-mode sidebar contrast
docs(staging): make dropdowns work under apache.org CSP
- Remove blocked jsdelivr Bootstrap/Popper scripts

- Remove duplicate documentation_options.js include

- Add small CSP-safe JS for dropdown + theme selection

docs(staging): apply PR1270 theme assets + navbar toggle markup

- Sync generated theme CSS assets used by the Sphinx theme

- Keep theme toggle inside the navbar links container (stable positioning)
@kaxil
Copy link
Member Author

kaxil commented Dec 17, 2025

Works on staging:

https://airflow.staged.apache.org/

image image

Archive repo:

Currently only changed 3.1.5 but can easily update all soon after more folks have had chance to look at it

@choo121600
Copy link
Member

choo121600 commented Dec 17, 2025

trim.A0C6A3F7-2A12-418D-AFD1-6BFF36F8B868.MOV

There’s an issue with the dropdown layout on responsive screens, but overall it looks great!!! 😎

@kaxil kaxil merged commit 66043cc into main Dec 17, 2025
2 checks passed
kaxil added a commit to astronomer/airflow that referenced this pull request Dec 17, 2025
Part of apache/airflow-site#1270 so all newly released and dev versions are modernized and support dark mode
kaxil added a commit to apache/airflow that referenced this pull request Dec 17, 2025
Part of apache/airflow-site#1270 so all newly released and dev versions are modernized and support dark mode
@kaxil
Copy link
Member Author

kaxil commented Dec 17, 2025

Merged, will be gradually rolled out to older AF, Providers, Helm Chart and other docs.

@potiuk
Copy link
Member

potiuk commented Dec 17, 2025

Nice! ..

kaxil added a commit to astronomer/airflow that referenced this pull request Dec 17, 2025
Part of apache/airflow-site#1270 so all newly released and dev versions are modernized and support dark mode

(cherry picked from commit 4713f72)
kaxil added a commit to astronomer/airflow that referenced this pull request Dec 17, 2025
Part of apache/airflow-site#1270 so all newly released and dev versions are modernized and support dark mode

(cherry picked from commit 4713f72)
@bugraoz93
Copy link
Contributor

Amazing Kaxil, many thanks!

FoxHelms pushed a commit to FoxHelms/airflow that referenced this pull request Dec 17, 2025
Part of apache/airflow-site#1270 so all newly released and dev versions are modernized and support dark mode
@kaxil kaxil deleted the feat-modernize-theme-5qPcf branch December 18, 2025 00:19
Lohith625 pushed a commit to Lohith625/airflow that referenced this pull request Dec 19, 2025
Part of apache/airflow-site#1270 so all newly released and dev versions are modernized and support dark mode
potiuk pushed a commit to apache/airflow that referenced this pull request Dec 28, 2025
Part of apache/airflow-site#1270 so all newly released and dev versions are modernized and support dark mode

(cherry picked from commit 4713f72)
potiuk pushed a commit to apache/airflow that referenced this pull request Dec 28, 2025
Part of apache/airflow-site#1270 so all newly released and dev versions are modernized and support dark mode

(cherry picked from commit 4713f72)
ephraimbuddy pushed a commit to apache/airflow that referenced this pull request Jan 6, 2026
Part of apache/airflow-site#1270 so all newly released and dev versions are modernized and support dark mode

(cherry picked from commit 4713f72)
jhgoebbert pushed a commit to jhgoebbert/airflow_Owen-CH-Leung that referenced this pull request Feb 8, 2026
Part of apache/airflow-site#1270 so all newly released and dev versions are modernized and support dark mode
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

8 participants