Table of Contents
Mermaid Plugin
Compatible with DokuWiki
- 2024-02-06 "Kaos" yes
- 2023-04-04 "Jack Jackrum" yes
- 2022-07-31 "Igor" yes
- 2020-07-29 "Hogfather" yes
This plugin provides support for the diagramming tool Mermaid. Mermaid is a JavaScript based diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams dynamically.
Installation
Install the plugin using the Plugin Manager and the download URL above, which points to latest version of the plugin. Refer to Plugins on how to install plugins manually.
Examples/Usage
Provide the Mermaid code enclosed by the <mermaid>
tags:
<mermaid> graph TD A(**mermaid**)-->B((__plugin__)) A-->C(((//for//))) B-->D[["[[https://www.dokuwiki.org/dokuwiki|Dokuwiki]]"]] C-->D </mermaid>
results in
Mermaid supports multiple other diagrams besides the shown flowchart, for example:
- Sequence diagrams
- Gantt diagrams
- Class diagrams
- Git graphs
- User Journey diagrams
For full information, see https://mermaid.js.org/intro/.
Syntax
The full syntax is
<mermaid #width #height> #Content </mermaid>
#Content
specifies the code that gets passed on to Mermaid for rendering. #Width
and #Height
are optional parameters and are used to specify the size of the container of the diagram. They can take any value supported by CSS, for example <mermaid 100% 1cm>
. Default value is auto
.
For more examples and details on the syntax, see https://mermaid.js.org/intro/.
Raw Mode
If 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:
<mermaid> raw graph TD A(**mermaid**)-->B((__plugin__)) A-->C(((//for//))) B-->D[["[[https://www.dokuwiki.org/dokuwiki|Dokuwiki]]"]] C-->D </mermaid>
This 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.
Configuration and Settings
No further configuration is required.
Version and Location
You can choose which Mermaid version you want to use:
- the locally hosted version
- the remotely hosted, currently available, latest version
- a remotely hosted specific version
Default theme
You can choose which Mermaid theme should be used as a default. The available themes are the five integrated themes of Mermaid.
Known Problems
The syntax of Mermaid and DokuWiki can clash in rare cases. If you encounter problems, feel free to report them and open an issue.
You can sidestep these problems by using the raw mode which disables the processing by DokuWiki, or adjust your Mermaid code as shown below.
Usage of Brackets
Mermaid 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]]"]
Binding Click Events
Mermaid supports the binding of click events. This can and will clash with DokuWikis own handling of links. Instead of:
<mermaid> flowchart TD A[Link] click A "https://www.github.com" </mermaid>
please use
<mermaid> flowchart TD A["[[https://www.github.com|Link]]"] </mermaid>
DokuWiki Search Highlight
The 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.
Development
In the file action.php
, change the logLevel
of Mermaid to debug
for easier debugging by setting MERMAIDLOGLEVEL
to debug
.
License
This project is licensed under the GNU General Public License v2.0, included as LICENSE.
Mermaid is licensed under the MIT License, included as LICENSE Mermaid.
Change Log
- 2024-02-15
- Update to support the new Mermaid version 10.8
- Adds option to set site-wide default theme
- Fixes a possible problem due to the DokuWiki search highlight
- 2023-11-17
- Update to support the new Mermaid version 10.6
- 2023-09-04
- Added raw mode
- Update to support the new Mermaid version 10.4
- 2023-07-21
- Bug fix: Double brackets are now supported
- 2023-07-07
- Bug fix: Elk renderer now working for all versions
- 2023-07-04
- Update to support the new Mermaid version 10.2
- 2023-04-05
- Update to support the new Mermaid version 10.1
- 2023-02-28
- Update to support the new Mermaid version 10.0
- 2023-02-03
- Added setting to choose between a locally or remotely hosted mermaid file
- 2023-01-26
- Initial release with Mermaid version 9.3