README.md
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.9.0](https://github.com/mermaid-js/mermaid/releases/tag/mermaid%4011.9.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}