Jekyll & Markdown: Mermaid, Mathjax, Table of Context Posted by Jingyi on December 18, 2018. This is a page, trying to see if it is working. Test of Mermaid. A CLI tool for publishing markdown articles to dev.to. The tool will also update articles if they already exist on dev.to.

• Mermaid Markdown Syntax
• Mermaid Markdown Themes
• Mermaid Github Markdown
• Mermaid Markdown Style

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.

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.

Mermaid Markdown 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.

Mermaid Markdown Themes

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).

Mermaid Github Markdown

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.

Join 1000s of developers learning about Enterprise-grade Node.js & JavaScript

Compile Mermaid Markdown

*.mermaid, *.mmd files or *.md with mermaid codeblocks and compile them

Installation

Copy and paste the following snippet into your .yml file.

Purpose

Markdown is a common way to present useful information with rich formatting from a simple human readable syntax. Especially useful is being able to highlight code blocks.

Mermaid-JS takes this philosophy and applies it to graphs! Taking simple human-readable syntax and returning rich graphs.

Github markdown does not automatically render mermaid to the browser, so this action does that for you so you can just worry about the markdown and not the toolchain.

Contributing

Looking for suggestions/help in improving this action. If there is a feature you want, or you encounter a bug, please let me know and we can work together to improve it.

How to use

The idea is that this action is to be used within a workflow, not as a standalone action at this time.OUTPUT_FILE_TYPE can be used to define the output file type, if you don't specify it it will default to png. You can override it to svg or pdf.

Sample workflow with automated PR

Mermaid Markdown Style

(adapted from my example repo:

Sample workflow with changes pushed

Compile Mermaid Markdown is not certified by GitHub. It is provided by a third-party and is governed by separate terms of service, privacy policy, and support documentation.