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. [Further Information](#further-information) 117. [License](#license) 12 13## Installation 14 15Install 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. 16 17## Basic example 18 19Provide the Mermaid code enclosed by the ```<mermaid>``` tags: 20 21 <mermaid> 22 graph TD 23 A(**mermaid**)-->B((__plugin__)) 24 A-->C(((//for//))) 25 B-->D[["[[https://www.dokuwiki.org/dokuwiki|Dokuwiki]]"]] 26 C-->D 27 </mermaid> 28 29This will be rendered by the plugin and shown as: 30 31 32 33For more examples and details on the Mermaid syntax, see https://mermaid.js.org/intro/. 34 35## Further Functionality 36 37### Size Adjustmens 38 39The width and height of the container of the diagram can be adjusted using 40 41 <mermaid #width #height> 42 43where #width and #height can take any value supported by CSS, for example: 44 45 <mermaid 100% 1cm> 46 47### Raw mode 48 49If 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. 50 51 <mermaid> 52 raw 53 graph TD 54 A(**mermaid**)-->B((__plugin__)) 55 A-->C(((//for//))) 56 B-->D[["[[https://www.dokuwiki.org/dokuwiki|Dokuwiki]]"]] 57 C-->D 58 </mermaid> 59 60This 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. 61 62### �� Exporting Diagrams 63 64To 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. 65 66### �� �� No Client Side Diagram Conversion 67 68By 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. 69 70This 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). 71 72To 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. 73 74## Configuration and Settings 75 76No further configuration is required. 77 78### Version and Location 79 80You can choose which Mermaid version you want to use: 81 82 - The locally hosted version (currently version [11.2.1](https://github.com/mermaid-js/mermaid/releases/tag/mermaid%4011.2.1)), 83 - the remotely hosted, currently available, latest version or 84 - a remotely hosted specific version. 85 86### Default theme 87 88You can choose which Mermaid theme should be used as a default. The available themes are the five [integrated themes of Mermaid](https://mermaid.js.org/config/theming.html#available-themes). 89 90## Known Problems 91 92Allmost 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. 93 94You 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. 95 96### Usage of Brackets 97 98Mermaid 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]]"]```. 99 100### Binding Click Events 101 102Mermaid 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 103 104 <mermaid> 105 flowchart TD 106 A[Link] 107 click A "https://www.github.com" 108 </mermaid> 109 110please use 111 112 <mermaid> 113 flowchart TD 114 A["[[https://www.github.com|Link]]"] 115 </mermaid> 116 117### DokuWiki Search Highlight 118 119The 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. 120 121## Further Information 122 123Mermaid supports multiple other diagrams besides the shown flowchart, for example: 124 - Sequence diagrams 125 - Gantt diagrams 126 - Class diagrams 127 - Git graphs 128 - User Journey diagrams 129 130For more information, see https://mermaid.js.org/intro/. 131 132## License 133 134This project is licensed under the GNU General Public License v2.0. See the [LICENSE](LICENSE) file for details. 135 136Mermaid is licensed under the MIT License. See the [LICENSE Mermaid](LICENSE%20Mermaid) file for details.
){kind=link}