1# Mermaid Plugin for DokuWiki 2 3This is a plugin for [Dokuwiki](https://www.dokuwiki.org/dokuwiki). It provides support for the diagramming tool [Mermaid](https://mermaid.js.org/). Mermaid is a JavaScript based diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams dynamically. 4 51. [Installation](#installation) 62. [Basic example](#basic-example) 73. [Further Functionality](#further-functionality) 84. [Configuration and Settings](#configuration-and-settings) 95. [Known Problems](#known-problems) 106. [License](#license) 11 12## Installation 13 14Install the plugin using the [Dokuwiki Plugin Manager](https://www.dokuwiki.org/plugin:plugin). Refer to [Plugins](https://www.dokuwiki.org/plugins|Plugins) on how to install plugins manually. 15 16⚠️ The plugin requires PHP 8.0+ to function properly. 17 18## Basic example 19 20Provide the Mermaid code enclosed by the ```<mermaid>``` tags: 21 22 <mermaid> 23 graph TD 24 A(**mermaid**)-->B((__plugin__)) 25 A-->C(((//for//))) 26 B-->D[["[[https://www.dokuwiki.org/dokuwiki|Dokuwiki]]"]] 27 C-->D 28 </mermaid> 29 30This will be rendered by the plugin and shown as: 31 32 33 34 Mermaid supports multiple other diagrams besides the shown flowchart, for example: 35 36- Sequence diagrams 37- Gantt diagrams 38- Class diagrams 39- Git graphs 40- User Journey diagrams 41 42For more examples and details on the Mermaid syntax, see <https://mermaid.js.org/intro/>. 43 44## Further Functionality 45 46### Size Adjustmens 47 48The width and height of the container of the diagram can be adjusted using 49 50 <mermaid #width #height> 51 52where #width and #height can take any value supported by CSS, for example: 53 54 <mermaid 100% 1cm> 55 56### Raw Mode 57 58If needed, the Mermaid code can be passed on without any processing or rendering by DokuWiki. Insert a line containing only the word raw before the Mermaid code. 59 60 <mermaid> 61 raw 62 graph TD 63 A(**mermaid**)-->B((__plugin__)) 64 A-->C(((//for//))) 65 B-->D[["[[https://www.dokuwiki.org/dokuwiki|Dokuwiki]]"]] 66 C-->D 67 </mermaid> 68 69This allows to use the full feature set of Mermaid without interference from DokuWiki, albeit at the expanse of not being able to use any functionality provided by DokuWiki. 70 71### �� Exporting Diagrams 72 73❗ [Enable the save button](#visibility-of-save-and-lock-button) in the configuration first, if you want to use this functionality. 74 75To export a diagram, simply hover your mouse over the diagram to reveal the Save button. Clicking it will allow you to download the diagram in SVG format, preserving the exact appearance as rendered by Mermaid. 76 77### �� �� No Client Side Diagram Conversion 78 79❗ [Enable the lock button](#visibility-of-save-and-lock-button) in the configuration first, if you want to use this functionality. 80 81By default, Mermaid diagrams are converted from Mermaid syntax to SVG on the client side. To change this to get the SVG directly form the server, simply hover your mouse over the diagram to reveal the Lock button. Clicking it will include the SVG directly in a new page revision, eliminating the need for client-side transformation. 82 83This can be useful for archiving pages or for use with other plugins that do not work with client side changes like [dw2pdf](https://www.dokuwiki.org/plugin:dw2pdf). 84 85To unlock and edit the diagram again, hover over it to reveal the Unlock button. Clicking it will remove the embedded SVG in a new page revision, allowing for further modification. 86 87## Configuration and Settings 88 89No further configuration is required. 90 91### Version and Location 92 93You can choose which Mermaid version you want to use: 94 95- The locally hosted version (currently version [11.5.0](https://github.com/mermaid-js/mermaid/releases/tag/mermaid%4011.5.0)), 96- the remotely hosted, currently available, latest version or 97- a remotely hosted specific version. 98 99### Default Theme and Look 100 101Choose which Mermaid theme and look should be used as a default. There are [eight themes and three looks](https://docs.mermaidchart.com/blog/posts/mermaid-innovation-introducing-new-looks-for-mermaid-diagrams) available. 102 103### Log Level 104 105Set the [log level](https://mermaid.js.org/config/schema-docs/config.html#loglevel) of mermaid. 106 107### Visibility of Save and Lock Button 108 109Choose the visibility of the save and lock button for the Mermaid diagrams. If their visibility is off, their respective functionality is not available. 110 111## Known Problems 112 113Almost all of the DokuWiki syntax is supported. In rare cases it can clash with the syntax of Mermaid. If you encounter any problems, feel free to report them and open an issue. 114 115You can sidestep these problems by using the [raw mode](#raw-mode) which disables the processing by DokuWiki, or adjust your Mermaid code as shown below. 116 117### Usage of Brackets 118 119Mermaid and DokuWiki both use brackets. If you need to use them both at the same time, make your intentions clear by using quotation marks like ```["[[link]]"]```. 120 121### Binding Click Events 122 123Mermaid supports the [binding of click events](https://mermaid.js.org/syntax/flowchart.html#interaction). This can and will clash with DokuWikis own handling of links. In general, use DokuWiki style links instead of click events, i. e. instead of 124 125 <mermaid> 126 flowchart TD 127 A[Link] 128 click A "https://www.github.com" 129 </mermaid> 130 131please use 132 133 <mermaid> 134 flowchart TD 135 A["[[https://www.github.com|Link]]"] 136 </mermaid> 137 138### DokuWiki Search Highlight 139 140The search highlight of the DokuWiki search can prevent the proper parsing of the diagram, leading to an error. For that reason, it is disabled for the Mermaid diagrams. The search itself is not affected. 141 142## License 143 144This project is licensed under the GNU General Public License v2.0. See the [LICENSE](LICENSE) file for details. 145 146Mermaid is licensed under the MIT License. See the [LICENSE Mermaid](LICENSE%20Mermaid) file for details. 147
){kind=link}