feat: mermaid diagrams, callouts, reader polish and a manual release workflow

[KristofersOzolinsMagebit]

What changes

Mermaid diagrams — a ```mermaid fence is drawn in the browser. Mermaid 11.17.2 is vendored (no CDN, works under the enforced admin CSP) and only loaded on pages that contain a diagram. A diagram Mermaid cannot read keeps its source visible with a short message. The vendored file is the official build wrapped in one line above and one below, because two libraries bundled inside it (fastdom, fastdom-promised) look for RequireJS before CommonJS and would otherwise register as AMD modules; CI strips the wrapper and checks the official sha256.

Callouts — GitHub-style > [!NOTE] / [!TIP] / [!IMPORTANT] / [!WARNING] / [!CAUTION] blockquotes render as coloured boxes with a title and icon. Implemented as a CommonMark extension; plain blockquotes are untouched.

Reader polish — footnotes, the "On this page" panel follows the heading being read, images and drawn diagrams open full screen on click (Esc closes, focus is restored), wide tables scroll sideways instead of breaking the layout, external links carry a small arrow, and a print stylesheet hides the chrome.

Manual release workflow — Release runs from the Actions tab only (workflow_dispatch, master only). git-cliff works out the next version from the conventional commits since the last tag (feat → minor, fix/others → patch, breaking → major), with a bump override and a dry_run input. It regenerates CHANGELOG.md, commits it, tags vX.Y.Z, pushes both and publishes a GitHub release. CHANGELOG.md is generated now for the existing history and registered in the viewer via <changelog>. A protected master needs a RELEASE_TOKEN secret or an Actions bypass — see the README.

Verification

• PHPStan level 9, phpcs (Magento2, warnings fatal) and 315 unit tests pass; new tests cover the Mermaid and Callout extensions.
• Checked in the admin with CSP in enforce mode: diagram renders, zoom works, callouts/footnotes/scroll-spy render, zero securitypolicyviolation events, no console errors. The failed-diagram path shows the message and removes Mermaid's stray error drawing.
• Both CI asset checks re-run locally (no external references, checksums match).

[magebit-automation]

✅ Magebit Code Review — Review complete

No blocking issues were found.

Magebit Review: The change is safe to merge. I checked the new callout and mermaid markdown code and their tests, the admin scripts that draw diagrams and open images full screen, how mermaid is bundled and hashed in CI, and the new manual release workflow.

Magebit Review

Critical: 0 · High: 0 · Medium: 1 · Low: 0 · Info: 0

Notable findings:

• [Medium] Release workflow pins git-cliff-action to a moving tag (.github/workflows/release.yml:56)

Changed files (27)

.github/

• .github/workflows/ci.yml +11 −1
• .github/workflows/release.yml +139 −0

Docs/

• Docs/3-writing-documentation.md +83 −1

Model/

• Model/Markdown/Callout/Callout.php +45 −0
• Model/Markdown/Callout/CalloutExtension.php +30 −0
• Model/Markdown/Callout/CalloutProcessor.php +103 −0
• Model/Markdown/Callout/CalloutRenderer.php +62 −0
• Model/Markdown/Mermaid/MermaidExtension.php +34 −0
• Model/Markdown/Mermaid/MermaidFenceRenderer.php +57 −0

Test/

• Test/Unit/Model/Markdown/Callout/CalloutExtensionTest.php +100 −0
• Test/Unit/Model/Markdown/Mermaid/MermaidExtensionTest.php +61 −0

etc/

• etc/di.xml +6 −0
• etc/documentation.xml +1 −0

i18n/

• i18n/en_US.csv +8 −0

view/

• view/adminhtml/requirejs-config.js +3 −0
• view/adminhtml/templates/documentation.phtml +3 −1
• view/adminhtml/templates/documentation/content.phtml +15 −0
• view/adminhtml/web/css/documentation.css +255 −0
• view/adminhtml/web/js/documentation.js +200 −1
• view/adminhtml/web/js/mermaid-boot.js +73 −0
• view/adminhtml/web/js/vendor/mermaid/LICENSE +21 −0
• view/adminhtml/web/js/vendor/mermaid/README.md +11 −0
• view/adminhtml/web/js/vendor/mermaid/mermaid.min.js +3638 −0

(root)

• CHANGELOG.md +62 −0
• README.md +53 −2
• cliff.toml +67 −0
• composer.json +2 −1

View this run on the Portal →

💬 AI reviews are still being rolled out — your feedback shapes them. On the Portal run you can rate each finding, add a note to it, or leave feedback on the whole review. Leave feedback →

_{Reviewed by ~x-ai/grok-latest}

[magebit-automation]

[Medium] Release workflow pins git-cliff-action to a moving tag
_{security · general profile · confidence 90%}

The new release job can push commits and tags to master, but it loads orhun/git-cliff-action from the moving tag v4. Anyone who can move that tag can change what runs with write access to this repository.

The git-cliff binary is already pinned (version: v2.14.1). Do the same for the action itself at both call sites (this step and the release-notes step around line 94): pin the full commit SHA and leave # v4 as a comment so updates stay readable.

Suggested fix

uses: orhun/git-cliff-action@3d96a18 # v4