Upgrade Docsy theme from v0.12.0 to v0.14.2
- Dominant language
- HTML
- Stars
- 174
- Forks
- 432
- Avg merge
- 1d 17h
- Merged PRs (30d)
- 15
Description
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 `` 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
Contributor guide
No contributing guide indexed for this repository
Research direction
Review .github/workflows/build.yml, layouts/partials/sidebar-tree.html, and main-custom.scss against the Docsy v0.14.x templates and upgrade guidance. Run ./site.sh build-landing-pages first, then use ./site.sh preview-landing-pages to inspect the listed homepage, blog, code-block, docs-sidebar, community, and dark-mode checks. Done means a clean build, correct sidebar and code styling, and screenshots covering the requested pages.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- bootstrap, github-actions, html, scss, yaml
- Domain
- build-system, documentation, frontend
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100