Feature #44636
closed
Add Mermaid diagrams to the wiki syntax help pages
Description
Redmine can now render Mermaid code blocks as diagrams (#44425), but the wiki syntax help pages do not mention it yet, so users cannot learn about it from the help.
The attached patch adds a description of Mermaid diagrams to both help pages:
- Wiki Syntax Quick Reference (/help/wiki_syntax): A new "Mermaid diagrams" row shows a short example and its rendered result.
- Wiki formatting (/help/wiki_syntax/detailed): A new "Mermaid diagrams" section explains the following points: * Code blocks in the "mermaid" language are rendered as diagrams by Mermaid.js. The section links to the Mermaid syntax reference. * Mermaid.js is not bundled with Redmine. Diagrams are rendered only if the administrator has installed it. Otherwise, the code is displayed as a plain code block. * A rendered diagram can be downloaded as a PNG image.
The help pages do not load JavaScript, so the example diagrams are included as PNG images. These images were saved with the download link of rendered diagrams, so they look the same as what users see, and they can be regenerated in the same way.
The changes cover both the Textile and the CommonMark Markdown help pages. The English and Japanese pages are updated, and the pages for other languages include the English text until they are translated. The labels in the example images are in English and are shared by all languages.
Files
Related issues
Updated by Go MAEDA 24 days ago
- Related to Feature #44425: Render Mermaid code blocks as diagrams added
Updated by Go MAEDA 17 days ago
- File 0001-Describe-Mermaid-diagrams-in-the-wiki-syntax-help-pa.patch 0001-Describe-Mermaid-diagrams-in-the-wiki-syntax-help-pa.patch added
- File 0002-Add-English-Mermaid-help-to-languages-other-than-Eng.patch 0002-Add-English-Mermaid-help-to-languages-other-than-Eng.patch added
I have attached an updated patch that adds the following sentence after the link to the syntax reference in the detailed help, where 12.0.0 is the installed version:
Please note that the reference describes the latest version of Mermaid.js, and some of the syntax described there may not be supported by the installed version, 12.0.0.
The version installed in Redmine may be older than the one described in the reference. Without this note, users who follow the reference and find that their diagram is not rendered cannot easily tell that the cause is the version difference.
The version is inserted when the page is rendered, so the help pages do not need to be updated when the default version changes. It is taken from Redmine::Mermaid.installed_version, which reads the version from the installed mermaid.min.js, rather than from Redmine::Mermaid::VERSION, because administrators may install a different version. If the version cannot be determined, for example because Mermaid.js is not installed, the sentence is not shown.
The other changes in the patch are the same as in the previous one.