We have the following goals for diagrams on our wiki:
- Translatable - Diagrams must be translatable
- Easy to edit - No one wants to download another item of software to edit a diagram
- Collaborative - Diagrams like all other pages must be editable by multiple users.
Diagram Options
When creating Diagrams you have a number of options, these are ranked in order of preference and their alignment to our goals.
- Mermaid.js
- SVG
- PNG
Diagram Namespace
We have a "Diagram" namespace, that allows diagrams to have their own page, which allows for transclusion onto various pages. It will also be used in the future to enable easy caching and delivery of diagrams to other sources such as Resonite itself.
Including a Diagram in a page
To include a diagram in a page use this syntax:
{{Diagram:<diagram name>{{UseLangLink}}}}
This specific format uses the Template:UseLangLink template to suffix the diagram with the language of the page.
Using Mermaid
We're running Mermaid Js 10.8.0 which is the latest at the moment. This means that everything on Mermaid's website can be used.
To create a diagram it is recommended to:
- Create the diagram first using the Mermaid Js live editor.
- Copy and paste the diagram source into a new page in the "Diagram" namespace.
- Update the syntax to include the required Mermaid syntax(see below).
Mermaid Syntax
{{#mermaid:<your diagram from Mermaid editor}}
Mermaid Translation
When enabling translation on a mermaid diagram:
- Only wrap translate tags around text that needs to be translated.
- Always use <translate nowrap> to prevent issues with Mermaid rendering
- Use aliases where possible as this reduces the amount of translation strings. Most document types have an alias system.
Example
A good example Diagram in Mermaid is Diagram:LNLRelayConnection