kaxil opened a new issue, #77270: URL: https://github.com/apache/airflow/issues/77270
### Description Render the docs' mermaid diagrams in the browser with sphinxcontrib-mermaid 3.0 instead of drawing them into SVG files with mermaid-cli at build time. 3.0 changes what made build-time rendering necessary in #74757. It bundles Mermaid 12 in the package and serves it from the docs' own `_static`, with no inline script, so pages no longer import mermaid from cdn.jsdelivr.net and the ASF Content-Security-Policy stops being a blocker. It also adds pan and zoom (drag, Ctrl/Cmd+wheel, pinch, keyboard), a fullscreen overlay, and a capped scrolling view that keeps text in large diagrams readable (`mermaid_zoom`, `mermaid_toolbar`, `mermaid_max_height`, `mermaid_min_font_scale`). Their build-time SVG output still emits a plain `<object>`, so the new behaviour only comes with the client-side (`raw`) mode. ### Use case/motivation The database ERD page (https://airflow.apache.org/docs/apache-airflow/stable/database-erd-ref.html) is the case that hurts. The diagram is about 12000x8000 px and gets squeezed into the text column, so table and column names can't be read, and there's no way to zoom in. #77257 is a stopgap: clicking a diagram opens its SVG at full size, where the browser can zoom. With 3.0 in client-side mode: - Readers zoom, pan and go fullscreen on the ERD without leaving the page. - The diagram is an inline `<svg>` and its source sits in a `<pre>` on the page, so table and column names are searchable again. That was the goal of #72006, which build-time SVG in an `<object>` partly lost. - The docs build no longer needs mermaid-cli and Chromium. `scripts/in_container/install_mermaid_cli.sh`, `ensure_mermaid_cli` in `build_docs.py`, the puppeteer config and the font workaround in `devel-common/src/sphinx_exts/mermaid_svg.py` could all go. Before switching: - Wait for 3.0.0 final (3.0.0a1 is from 15 Nov 2026) and the dependency cooldown. - 3.0.0a1 adds its 8.6 MB of bundled assets to `html_static_path` in every client-side build, whether or not the project has a diagram. `mermaid_svg` is in `BASIC_SPHINX_EXTENSIONS`, so every provider's docs would ship that copy per version, while only a handful of packages have diagrams. I opened mgaitan/sphinxcontrib-mermaid#281 to copy the assets only when a document has a diagram. If it doesn't land, we can load the extension only in the packages that use it. - Check how long the 57-table ERD takes to lay out in the browser, since that now happens on every page load. - sphinx-airflow-theme isn't one of the themes 3.0 takes diagram colours from, so dark mode needs the `--mermaid-*` CSS variables set in the theme. - Check Firefox and Safari as well as Chromium. ### Related issues #72006 (ERD rendered with mermaid), #74757 (mermaid drawn at build time because of the ASF CSP), #77257 (stopgap: click a diagram to open it at full size), #36842 ### Are you willing to submit a PR? - [x] Yes I am willing to submit a PR! ### Code of Conduct - [x] I agree to follow this project's [Code of Conduct](https://github.com/apache/airflow/blob/main/CODE_OF_CONDUCT.md) -- 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]
