Render Mermaid and other GFM in iteration descriptions
What does this MR do and why?
Mermaid diagrams in an iteration description show as raw code on the iteration report, even though the edit preview renders them. The same goes for math, GLQL, syntax highlighting, reference popovers, and the image lightbox.
The report injects the backend-rendered descriptionHtml with v-safe-html but never calls renderGFM on it, and that call is what turns those placeholders into live content. Milestones had the same gap, fixed in Fix bug regarding broken mermaid markdown rendering in milestone view.
The report now watches iteration.descriptionHtml and calls renderGFM on the description element after it renders, so it runs on first load and again whenever the description changes (for example, after saving an edit). The watcher mirrors deployment_header.vue, and the component releases the image lightbox on unmount like the other routed description renderers do.
Iterations without a description, and all other parts of the report, behave as before.
References
Closes #497155 (closed)
- Mermaid Graphs in Iteration: marked Ready for development and quick win by the owning team, pointing at the milestone fix as the template.
- Fix bug regarding broken mermaid markdown rendering in milestone view: the same fix for milestones.
- Fix for rendering mermaid: an earlier community attempt, closed for inactivity. It re-ran
renderGFMfrom theupdated()hook, which fires on every re-render of the report (burndown totals, tab changes). This MR runs only when the description HTML changes, and a spec covers that.
Where iteration descriptions render
ee/app/assets/javascripts/iterations/components/iteration_report.vue: the only placedescriptionHtmlfor an iteration reaches the page. Fixed here.iteration_cadence_list_item.vueanditeration_cadences_list.vue: show iteration titles and dates only, no description.- Cadence descriptions: plain-text form field, never rendered as HTML.
- There is no HAML iteration show page; every iteration route goes through the
iteration_cadences#indexVue app.
Screenshots or screen recordings
| View | Before | After |
|---|---|---|
| Description: Mermaid, Ruby highlighting, math | ![]() |
![]() |
| After Edit, change the diagram, Save | ![]() |
![]() |
| Description, dark mode | ![]() |
![]() |
| Whole report page | ![]() |
![]() |
| Charts and issues (unchanged) | ![]() |
![]() |
Captured locally with a seeded iteration (Premium, iterations licensed) whose description holds a Mermaid block, a Ruby code block, and inline math. The edit row goes through Actions, Edit, adds a fourth node, and saves, so the report remounts with the new description. Charts and issues match apart from sub-pixel anti-aliasing on text edges, because the description above them changes height (mean pixel difference 0.14%). A description change while the report stays mounted is covered by the jest spec, not shown here.
How to set up and validate locally
-
Go to
http://gdk.test:3000/groups/gitlab-org/-/cadences/new, clear Enable automatic scheduling, give it a title, and save. -
On the cadence's actions menu, select Add iteration. Set start and due dates, and paste this into the description:
```mermaid graph LR A[Plan] --> B[Build] --> C[Ship] ``` $`a^2 + b^2 = c^2`$ -
Save. The iteration report shows the diagram and the formula rendered, not raw code.
-
Open the actions menu, select Edit, change the diagram (for example, add
C --> D[Learn]), and save. The report shows the updated diagram. -
On
master, the same steps show the Mermaid source and the raw formula.
MR acceptance checklist
Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.









