Upgrade ancient Docsy theme and implement dark mode#1270
Conversation
2e609f3 to
1624ace
Compare
|
Looking at it from fresh eyes:
|
jason810496
left a comment
There was a problem hiding this comment.
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!)
|
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. |
|
Nice! Welcome back @kaxil ! |
potiuk
left a comment
There was a problem hiding this comment.
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?
|
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 We have some docs how to do it in Again - wy might simply get the staging-archive branch and sync it to staging s3. |
jscheffl
left a comment
There was a problem hiding this comment.
Not that I think I can contribute any meaningful review but... cool!
Welcome back!
|
Wow Coool🚀🚀🚀 |
… 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/.
|
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)
1624ace to
dbcdb6e
Compare
- Add dark-mode overrides for Docsy/Sphinx left sidebar (CONTENT) toctree links
…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)
|
Works on staging: https://airflow.staged.apache.org/
Archive repo:
Currently only changed 3.1.5 but can easily update all soon after more folks have had chance to look at it |
trim.A0C6A3F7-2A12-418D-AFD1-6BFF36F8B868.MOVThere’s an issue with the dropdown layout on responsive screens, but overall it looks great!!! 😎 |
Part of apache/airflow-site#1270 so all newly released and dev versions are modernized and support dark mode
Part of apache/airflow-site#1270 so all newly released and dev versions are modernized and support dark mode
|
Merged, will be gradually rolled out to older AF, Providers, Helm Chart and other docs. |
|
Nice! .. |
Part of apache/airflow-site#1270 so all newly released and dev versions are modernized and support dark mode (cherry picked from commit 4713f72)
Part of apache/airflow-site#1270 so all newly released and dev versions are modernized and support dark mode (cherry picked from commit 4713f72)
|
Amazing Kaxil, many thanks! |
Part of apache/airflow-site#1270 so all newly released and dev versions are modernized and support dark mode
Part of apache/airflow-site#1270 so all newly released and dev versions are modernized and support dark mode
Part of apache/airflow-site#1270 so all newly released and dev versions are modernized and support dark mode (cherry picked from commit 4713f72)
Part of apache/airflow-site#1270 so all newly released and dev versions are modernized and support dark mode (cherry picked from commit 4713f72)
Part of apache/airflow-site#1270 so all newly released and dev versions are modernized and support dark mode (cherry picked from commit 4713f72)
Part of apache/airflow-site#1270 so all newly released and dev versions are modernized and support dark mode


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
Visual Changes
Implementation Details
Landing Pages (Hugo/Docsy)
showLightDarkModeMenu = truein config.tomlSphinx Documentation
Technical Requirements
$td-sidebar-tree-root-colorvariable (required by Docsy v0.2.0+)$font-awesome-font-namevariable (required by Docsy v0.6.0+).-bg-orangeutility class (required by Docsy v0.6.0+)pygments/_dark.scss(generated via:pygmentize -S github-dark)hooks/body-end.htmlfor webpack scripts (proper Docsy pattern)Testing