kaxil opened a new issue, #1413: URL: https://github.com/apache/airflow-site/issues/1413
The Docsy submodule (`landing-pages/site/themes/docsy`) is pinned to v0.12.0. The latest release is [v0.14.2](https://github.com/google/docsy/releases/tag/v0.14.2) ([upgrade guide](https://www.docsy.dev/blog/2026/0.14.0/)). > **Post-merge note**: PR #1443 upgraded to v0.14.3 and applied minimal fixes to get the build passing. However, the migration is incomplete — see [review comment](https://github.com/apache/airflow-site/pull/1443#issuecomment-4042543791) for details. The recommendations in sections 2 and 3 below were band-aids, not proper fixes. A follow-up PR is needed. ## Why upgrade - Bootstrap 5.3.6 → 5.3.8 - ScrollSpy TOC tracking - Better dark mode support - SCSS namespace cleanup (internal files moved under `td/`) - i18n improvements - Various navbar, sidebar, and layout fixes ## What needs to change ### 1. Hugo version bump (required) ✅ Docsy v0.14.0+ converted all i18n files from TOML to YAML. The YAML files contain bare `Yes`/`No` values (e.g. `feedback_positive: Yes`) which Hugo < 0.152.0 parses as booleans, causing build failure: ``` failed to load translations: unsupported file format bool ``` Hugo must be bumped from **0.146.0** to at least **0.152.0** in `.github/workflows/build.yml`. ### 2. `sidebar-tree.html` partial (required) ⚠️ needs follow-up Docsy v0.14.0 changed how `sidebar.html` calls `sidebar-tree.html`. Previously it passed the page context directly (`.`), now it passes a dict with `.context`, `.cacheSidebar`, `.sidebarRoot`, `.sidebarRootID`. Our custom `layouts/partials/sidebar-tree.html` assumes it receives the page directly. **What #1443 did** (band-aid): added `{{ $context := cond (isset . "context") .context . }}` to unwrap the page from the dict. **Problems with this approach**: - The `cond` backward-compat guard is dead code — since the same PR upgrades Docsy, `sidebar.html` always passes a dict. `isset . "context"` is always true. Should just be `{{ $context := .context }}`. - The custom override silently ignores `cacheSidebar`, `sidebarRoot`, and `sidebarRootID`. The new `sidebar.html` injects a `<script>` and adds `d-none` to `#td-sidebar-menu` expecting `sidebar-tree.html` to cooperate with cache-aware active-state rendering — our override doesn't participate. - The custom partial (71 lines) is severely out of sync with the upstream template (186 lines) — missing foldable nav, search, sidebar root support, configurable truncation, etc. **Proper fix**: evaluate whether the custom override is still needed. If so, rewrite it based on the new Docsy template. If not, delete it and use upstream. ### 3. `$enable-dark-mode` SCSS variable (required) ⚠️ needs follow-up Our `main-custom.scss` imports `td/code-dark` from Docsy. In v0.14.2, that file wraps its content in `@if $enable-dark-mode { ... }`. This variable is defined by Bootstrap, but our custom SCSS pipeline doesn't import Bootstrap (it's compiled separately from Docsy's `main.scss`). **What #1443 did** (band-aid): added `$enable-dark-mode: true !default;` before the import. **Problems with this approach**: - `!default` is meaningless — nothing defines this variable before this line, so the flag has no effect. - The comment says "we don't import bootstrap in Docsy's main.scss" — this is wrong. Bootstrap IS imported in Docsy's `td/_main.scss` (line 10). The issue is that `main-custom.scss` bypasses Docsy's pipeline entirely. - Setting `true` generates `[data-bs-theme='light']` and `[data-bs-theme='dark']` CSS selectors that may be dead CSS if dark mode isn't fully functioning. **Proper fix**: stop importing `td/code-dark` directly from `main-custom.scss` — it's an internal Docsy partial that now expects Bootstrap variables in scope. Either route through Docsy's SCSS pipeline or import Bootstrap's variables first. ### 4. Things that DON'T need changes - `.gitmodules` -- URL stays the same - `site.sh` -- build scripts unchanged - `config.toml` -- no config changes needed (site uses TOML, not YAML, so the yes/no token issue doesn't apply to our config) - Navbar -- we override with our own custom navbar, unaffected by Docsy's navbar refactor - `blocks/cover`, `td-offset-anchor`, Swagger UI -- not used ## How to verify The PR must include evidence that the site builds and renders correctly. Do not submit without doing these checks. ### Build verification 1. Run `./site.sh build-landing-pages` -- must complete with zero errors (webpack size warnings are fine) 2. The Hugo output should show `Total in XXX ms` with no `ERROR` lines ### Visual verification Run `./site.sh preview-landing-pages` and check these pages in a browser. Include screenshots in the PR for each: - **Homepage** (`/`) -- navbar renders correctly, footer links work, layout is intact - **Blog listing** (`/blog/`) -- post cards display properly - **A blog post with code blocks** (e.g. `/blog/airflow-three/`) -- code syntax highlighting works in both light and dark mode (this exercises the `td/code-dark` import) - **Docs sidebar** (`/docs/`) -- sidebar tree renders, navigation works, active page is highlighted (this exercises the `sidebar-tree.html` fix) - **Community page** (`/community/`) -- layout renders correctly - **Dark mode toggle** -- switch between light/dark mode on any page, verify no visual breakage ### What to watch out for - Broken code block styling (missing syntax highlighting, wrong colors) → indicates the `$enable-dark-mode` fix is wrong - Sidebar not rendering or erroring → indicates the `sidebar-tree.html` context unwrapping is wrong - Build error about "unsupported file format bool" → Hugo version not bumped - Any new Hugo deprecation warnings in the build output → note them in the PR but they don't block merge -- 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]
