feat/lesson-mermaid-diagrams - #123
Merged
Merged
Conversation
Lessons should render Mermaid fences as diagrams. ADR-0016 keeps the server out of it: commonmark-java already emits the fence as a sanitized code block (no extension exists or is needed), and the browser upgrades it to SVG with a lazily loaded, version-pinned, self-hosted Mermaid running at securityLevel strict. Server-side alternatives (mermaid-cli, Kroki) are rejected as infrastructure disproportionate to the feature. The code block stays in the DOM as the no-JavaScript, syntax-error, and accessibility fallback. Refs #122
Mermaid ships self-hosted through org.webjars.npm:mermaid so lesson diagrams never load from a CDN and the version is pinned where Dependabot can see it. The npm WebJar declares 21 npm-mirror transitive dependencies; a wildcard exclusion drops them all, leaving the single mermaid artifact, verified with dependency:tree. Spring Boot serves the bundle from the classpath at the versioned /webjars path; lesson pages require authentication, so the existing catch-all rule already authorizes it. Refs #122
The Mermaid feature has no server-side code at all: the browser renders whatever the sanitized code block contains (ADR-0016). That makes the renderer output the load-bearing contract, so a test pins it: the language-mermaid class and the diagram source survive rendering and sanitization, and no SVG appears in server output. Refs #122
Mermaid fences used to stay visible as source code. lesson-mermaid.js, the project's first client-side JavaScript feature, now upgrades them to SVG diagrams in the browser, exactly as ADR-0016 decided: the server keeps shipping sanitized code blocks and knows nothing about diagrams. The script loads the self-hosted Mermaid bundle lazily, only when the lesson actually contains a language-mermaid block, and initializes it with securityLevel strict. Each diagram gets a figure plus a show/hide source toggle wired with aria-expanded and aria-controls; the original code block stays in the DOM as the no-JavaScript, syntax-error, and screen-reader fallback (an accTitle line in the source becomes the SVG title). Diagrams follow the color scheme at load and re-render on scheme change; invalid diagrams degrade to the styled source block and Mermaid's detached error artifact is removed. Wide diagrams scroll inside the figure, never the page (RGAA 10.11). The lesson form hints at the fence and the accTitle line. Fixes #122
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## dev #123 +/- ##
=========================================
Coverage 81.57% 81.57%
Complexity 201 201
=========================================
Files 38 38
Lines 863 863
Branches 53 53
=========================================
Hits 704 704
Misses 125 125
Partials 34 34 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR renders Mermaid diagrams on lesson pages client-side with JavaScript.
It fixes #122.
ADR-0016 recorded the approach and architecture decision.
What problem does this PR solve?
Previously, lessons showed Mermaid fences only source, whereas students need rendered diagrams in the browser.
What changed?
lesson-mermaid.jsto:The server still outputs sanitized code blocks (ADR-0016).
lesson-mermaid.jsto upgrade mermaid code fences SVG diagrams with accessibility.language-mermaidclass and source survive rendering.