# Tag Syntax (not recommended) If you really don't want to use the code block syntax this plugin also supports using a tag wrapper for mermaidjs-diagrams like so: mermaid graph lR Documentation-with diagrams-is Awesome mermaid. Homebrew’s package index. A2ps: 4.14: Any-to-PostScript filter: a52dec: 0.7.4: Library for decoding ATSC A/52 streams (AKA 'AC-3').
Installation
Either use the npm or bower package managers as per below:
Or download a javascript bundle and a stylesheet, e.g. the urls below are for the default style and the all-in-one javascript - note that #version# should be replaced with version of choice:
Ex:
Checkout the latest version and other styles such as forest and dark.
There are some bundles to choose from:
- mermaid.js, mermaid.min.js This bundle contains all the javascript libraries you need to run mermaid
- mermaid.slim.js, mermaid.slim.min.js This bundle does not contain d3 which is useful for sites that already have d3 in place
- mermaidAPI.js, mermaidAPI.min.js, This bundle does not contain the web integration provided in the other packages but has a render function instead returns svg code.
Important:
It's best to use a specific tag or commit hash in the URL (not a branch). Files are cached permanently after the first request.
Read more about that at https://rawgit.com/
Simple usage on a web page
The easiest way to integrate mermaid on a web page requires two elements:
- Inclusion of the mermaid framework in the html page using a script tag
- A graph definition on the web page
Mermaid Js Syntax Examples
If these things are in place mermaid listens to the page load event and when fires, when the page has loaded, it will
locate the graphs n the page and transform them to svg files.
Include mermaid on your web page:
Further down on your page mermaid will look for tags with class='mermaid'. From these tags mermaid will try to
read the chart definiton which will be replaced with the svg chart.
Define a chart like this:
Would end up like this:
An id is also added to mermaid tags without id.
Labels out of bounds
If you use dynamically loaded fonts that are loaded through CSS, such as Google fonts, mermaid should wait for the
whole page to have been loaded (dom + assets, particularly the fonts file).
$(document).load(function() {
mermaid.initialize();
});
over
$(document).ready(function() {
mermaid.initialize();
});
Not doing so will most likely result in mermaid rendering graphs that have labels out of bounds. The default integration
in mermaid uses the window.load event to start rendering.
Mermaid Js Syntax Error
Calling mermaid.init
By default, mermaid.init will be called when the document is ready, finding all elements withclass='mermaid'. If you are adding content after mermaid is loaded, or otherwise need
finer-grained control of this behavior, you can call init yourself with:
- a configuration object
- some nodes, as
- a node
- an a array-like of nodes
- or W3C selector that will find your nodes
Example:
Or with no config object, and a jQuery selection:
This type of integration is deprecated instead the preferred way of handling more complex integration is to us the mermaidAPI instead.Usage with browserify
The reader is assumed to know about CommonJS style of module handling and how to use browserify. If not a good place
to start would be http://browserify.org/ website.
Minimalistic javascript:
Bundle the javascript with browserify.
Us the created bundle on a web page as per example below:
API usage
The main idea with the API is to be able to call a render function with graph defintion as a string. The render function
will render the graph and call a callback with the resulting svg code. With this approach it is up to the site creator to
fetch the graph definition from the site, perhaps from a textarea, render it and place the graph somewhere in the site.
To do this, include mermaidAPI on your web website instead of mermaid.js. The example below show an outline of how this
could be used. The example just logs the resulting svg to the javascript console.
Sample of API usage together with browserify
Binding events
Sometimes the generated graph also has defined interactions like tooltip and click events. When using the API one must
add those events after the graph has been inserted into the DOM.
The example code below is an extract of wheat mermaid does when using the API. The example show how it is possible to
bind events to a svg when using the API for rendering.
- The graph is generated using the render call.
- After generation the render function calls the provided callback function, in this case its called insertSvg.
- The callback function is called with two parameters, the svg code of the generated graph and a function. This
function binds events to the svg after it is inserted into the DOM. - Insert the svg code into the DOM for presentation
- Call the binding function that bainds the events
Example of a marked renderer
This is the renderer used for transforming the documentation from markdown to html with mermaid diagrams in the html.
Another example in coffeescript that also includes the mermaid script tag into the generated markup.
Advanced usage
Error handling
When the parser encounters invalid syntax the mermaid.parseError function is called. It is possible to override this
function in order to handle the error in an application specific way.
Parsing text without rendering
It is also possible to validate the syntax before rendering in order to streamline the user experience. The function
mermaid.parse(txt) takes a text string as an argument and returns true if the text is syntactically correct and
false if it is not. The parseError function will be called when the parse function returns false.
The code-example below in meta code illustrates how this could work:
Mermaid takes a number of options which lets you tweak the rendering of the diagrams. Currently there are three ways of
setting the options in mermaid.
- Instantiation of the configuration using the initialize call
- Using the global mermaid object - deprecated
- using the global mermaid_config object - deprecated
- Instantiation of the configuration using the mermaid.init call
The list above has two ways to many of doing this. Three are deprecated and will eventually be removed. The list of
configuration objects are described in the mermaidAPI documentation.
Using the mermaidAPI.initialize/mermaid.initialize call
The future proof way of setting the configuration is by using the initialization call to mermaid or mermaidAPi depending
on what kind of integration you use.
Using the mermaid object
Is it possible to set some configuration via the mermaid object. The two parameters that are supported using this
approach are:
- mermaid.startOnLoad
- mermaid.htmlLabels
Using the mermaid_config
Is it possible to set some configuration via the mermaid object. The two parameters that are supported using this
approach are:
- mermaid_config.startOnLoad
- mermaid_config.htmlLabels
Using the mermaid.init call
Is it possible to set some configuration via the mermaid object. The two parameters that are supported using this
approach are:
- mermaid_config.startOnLoad
- mermaid_config.htmlLabels
Add diagrams to your JAMStack (Jekyll/Hugo/Gatsby) blog with Mermaid JS
The following post will go through how to integrate Mermaid JS, a “simple markdown-like language for generating charts”.
It will initially go through the benefits of MermaidJS, followed by a generic (cross-technology) integration, finally it will tackle the Hugo-way of dealing with this issue.
Table of Contents
Why MermaidJS?
Mermaid is a “a simple markdown-like script[ing] language for generating charts from text via javascript”,it fits very well within a text-driven workflow on top of the JAMStack.
This is because Markdown is one of the top options of the M (Markdown) component of JAMStack, soit makes sense to add a “markdown-like” language to create diagrams within your Hugo/Gatsby/Hexo/Jekyll posts.
Mermaid allows you to defined charts using text like the following:
Which looks like the following (see it here if you have JS disabled):
The simplest/most generic MermaidJS integration
No Hugo required, this approach will work for any site where you can edit theposts as HTML/Markdown (where HTML div-s are allowed) and you can add <script> tags
This is the simplest integration:
Feel free to include the script tag anywhere on the page, it’s marked as async so should not render blocking regardless. For more information about async, see the script tag MDN documentation
We’re leveraging unpkg.com, “a fast, global content delivery network for everything on npm”.
Unfortunately for users of Hugo, this breaks out of the Hugo paradigm since it just injects HTML into pages.
Integrating MermaidJS as a Hugo shortcode
What is a Hugo shortcode?
Often, content authors are forced to add raw HTML (e.g., video <iframes>) to Markdown content. We think this contradicts the beautiful simplicity of Markdown’s syntax.
Hugo created shortcodes to circumvent these limitations.
A shortcode is a simple snippet inside a content file that Hugo will render using a predefined template. Note that shortcodes will not work in template files.
In other words: shortcodes are ways to abstract functionality that you wouldinteract with in your content (Markdown) files.
Usage example would be with the tweet built-in shortcode example from the Hugo docs:
Which renders as:
You can escape @GoHugoIO shortcode syntax using /* */ eg.
{{</* tweet tweet-id */>}}
Shortcodes with a body using .Inner
Add the following shortcode to layouts/shortcodes/mermaid.html:
By using .Inner, our shortcode can be used as follows:
Which is handier than the alternative which is passing parameters into theshortcode in a way akin to React/Vue/Angular props or HTML attributes (see the tweet example earlier in the post).
Loading the MermaidJS script only on pages that need it
Add the following conditionals around the script:
This is will make sure that mermaid.min.js does not get loaded unless the post specifically says that it needs it.
In your post (or other) frontmatter:
In your post content you can now write Mermaid diagrams:
Make sure to switch on mermaid: true otherwise you’ll just see the following text
graph TD;A–>B;A–>C;B–>D;C–>D;
Get The Jest Handbook (100 pages)
Take your JavaScript testing to the next level by learning the ins and outs of Jest, the top JavaScript testing library.
orJoin 1000s of developers learning about Enterprise-grade Node.js & JavaScript