Fix stacked modals on Mermaid diagrams and squished figure captions#405
Fix stacked modals on Mermaid diagrams and squished figure captions#405JakeSCahill wants to merge 2 commits into
Conversation
✅ Deploy Preview for docs-ui ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
📝 WalkthroughWalkthroughThe changes add top spacing for Mermaid diagram captions, prevent Mermaid-containing image blocks from opening the image expansion modal, and remove the trailing modal overlay element from the feedback form template. Estimated code review effort: 1 (Trivial) | ~5 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Mermaid diagrams are wrapped in an imageblock div, so the generic expand-images lightbox bound to them alongside the dedicated Mermaid zoom modal. One click opened both overlays stacked, and closing the Mermaid modal left the plain lightbox behind. Skip imageblocks that contain a Mermaid diagram when binding the generic lightbox. Mermaid SVGs have no internal bottom padding, so the 0.5rem figure caption margin looked squished against the diagram. Give Mermaid captions 1.25rem. Also remove a dead, duplicate #modal-overlay div from the feedback form partial. Nothing references it, and the duplicate id breaks getElementById-based checks against the real overlay.
9c3c62a to
36fa6fd
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/css/mermaid.css`:
- Around line 7-11: Update the Mermaid caption selector in the `.doc
.imageblock` rule to match `.title` elements that follow `.mermaid` even when an
intervening sibling wrapper exists, while keeping the match scoped to the image
block and preserving the existing margin.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: f14c9eb2-52f3-408f-9bdc-2ee197a28d9c
📒 Files selected for processing (3)
src/css/mermaid.csssrc/js/07-expand-images.jssrc/partials/feedback-forms.hbs
💤 Files with no reviewable changes (1)
- src/partials/feedback-forms.hbs
| /* Mermaid SVGs have no internal bottom padding, so the figure caption | ||
| needs more separation than a regular image caption. */ | ||
| .doc .imageblock .mermaid + .title { | ||
| margin-top: 1.25rem; | ||
| } |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
rg -n -C 6 'mermaid|imageblock|class="title"|class="content"' . \
--glob '*.hbs' --glob '*.adoc' --glob '*.html' --glob '*.js'Repository: redpanda-data/docs-ui
Length of output: 20505
🌐 Web query:
Antora asciidoctor asciimath mermaid block imageblock generated HTML .mermaid .content .title
💡 Result:
In Antora, Mermaid diagrams are not supported out-of-the-box by Asciidoctor and require specific extensions [1][2][3]. There are two primary ways to handle them: via the @sntke/antora-mermaid-extension (client-side rendering) or via extensions like asciidoctor-kroki (server-side rendering) [1][4]. Client-side rendering with @sntke/antora-mermaid-extension: This extension preserves the Mermaid source in the generated HTML [1][5]. When a [mermaid] block is processed, it typically outputs a block element (often a div or pre) assigned the CSS class.mermaid [5]. The structure of the generated HTML generally includes:.mermaid: The container element for the diagram [5]..content: Within the container, the raw text definition of the Mermaid diagram is preserved [5]..title: If a title is provided for the block in AsciiDoc (e.g.,.Diagram Title), it is rendered by Asciidoctor and typically appears as a separate element (e.g.,.title) associated with the block [5]. Configuration: To use this, you must add the extension to your antora-playbook.yaml under the antora.extensions section, not the asciidoc.extensions section [1][6]. You will also need to ensure the Mermaid.js library is loaded via your UI bundle's scripts [1][7]. Server-side rendering with Kroki: Alternatively, using asciidoctor-kroki allows for rendering diagrams into image files (e.g., SVG or PNG) at build time [8][4]. In this approach, the output is typically a standard AsciiDoc block image [9]. This is configured by adding asciidoctor-kroki to the asciidoc.extensions list in your playbook [4]. Important Note: If you are using the @sntke/antora-mermaid-extension, be aware that misconfiguration of attributes in your antora.yml can sometimes interfere with block processing [5]. Always ensure you are targeting the correct extension facility (Antora vs. Asciidoctor) based on your chosen rendering method [6].
Citations:
- 1: https://github.com/snt/antora-mermaid-extension/blob/master/README.md
- 2: https://github.com/snt/antora-mermaid-extension
- 3: https://docs.asciidoctor.org/diagram-extension/latest/
- 4: Document how to use with Antora asciidoctor/asciidoctor-kroki#37
- 5: Generated pre element is missing mermaid class snt/antora-mermaid-extension#11
- 6: https://docs.antora.org/antora/latest/playbook/asciidoc-extensions/
- 7: https://registry.npmjs.org/%40sntke%2Fantora-mermaid-extension
- 8: Render Mermaid diagrams in the Antora docs build quarkiverse/quarkus-mcp-server#773
- 9: https://docs.asciidoctor.org/asciidoc/latest/macros/images/
Target the direct children when matching Mermaid titles.
The current selector depends on .title being the immediate sibling of .mermaid; if the rendered block contains a sibling child wrapper before the title, the spacing rule won’t apply. Use a more direct structural selector, such as .doc .imageblock .mermaid + .title, to reduce reliance on sibling ordering without losing the intended target.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/css/mermaid.css` around lines 7 - 11, Update the Mermaid caption selector
in the `.doc .imageblock` rule to match `.title` elements that follow `.mermaid`
even when an intervening sibling wrapper exists, while keeping the match scoped
to the image block and preserving the existing margin.
Mermaid v10 and v11 flowcharts never reserve vertical space for a cluster label above nested subgraphs: the label overlaps the inner boxes' top borders, and neither flowchart.subGraphTitleMargin nor flowchart.padding changes the label-to-content distance (top shifts the label down into the content, bottom only grows the box downward). Post-process the rendered SVG instead: for each cluster whose label sits within 12px of a fully-contained child cluster, shift the label up, grow the cluster rect, and expand the viewBox for top-level clusters.
|
Suggestions for 08-mermaid-label-spacing.js (non-blocking)
|
Feediver1
left a comment
Feediver1
left a comment
There was a problem hiding this comment.
non-blocking suggestions
2 participants
Problems
<div class="imageblock">, so07-expand-images.jsbound its generic lightbox to Mermaid diagrams in addition to the dedicated zoom modal from20-mermaid-zoom.js. One click opened both overlays (Mermaid modal atz-index: 2147483647, generic at9999). Closing the Mermaid modal revealed the generic lightbox underneath: a dimmed page showing through the cloned transparent-background SVG, with a stray close button in the corner.0.5remfigure-caption margin left the caption pressed against the diagram's bottom boxes.#modal-overlay.feedback-forms.hbsshipped an empty<div class="modal-overlay" id="modal-overlay">that nothing references. It duplicates the id of the expand-images overlay, sogetElementById('modal-overlay')returns the dead element.Fixes
07-expand-images.js: skip imageblocks that contain a.mermaiddiagram when binding the generic lightboxmermaid.css:1.25remtop margin for figure captions that follow a Mermaid diagramfeedback-forms.hbs: remove the dead duplicate overlay divSecond commit: subgraph label spacing
Mermaid v10 and v11 flowcharts never reserve vertical space between a subgraph label and nested subgraphs: the label overlaps the inner boxes' top borders, and no configuration changes this (
flowchart.subGraphTitleMargin.bottomonly grows the box downward,.toppushes the label down into the content, andflowchart.paddingis a no-op for label-to-child distance; all measured at a constant -3px gap). A new08-mermaid-label-spacing.jspost-processes each rendered SVG: for any cluster whose label sits within 12px of a fully-contained child cluster, it shifts the label up, grows the cluster rect, and expands the viewBox for top-level clusters. Verified on the Stretch Cluster topology diagrams (label-to-content gap goes from -2px overlap to +8px clear space), with side-by-side and stacked sibling panels correctly left untouched.Verification
Reproduced both bugs on the live deploy-preview for redpanda-data/docs#1820 (Chrome DevTools protocol: real click opened both overlays; closing the Mermaid modal left
.modal-overlay.activebehind). Rebuilt the bundle with these fixes, built the docs site against it, and re-ran the same click sequence: only the Mermaid modal opens, closing it restores the page with no lingering overlay and body scroll intact, and the caption spacing renders with clear separation.gulp lintandgulp bundlepass.🤖 Generated with Claude Code