17

I am hoping to use mermaid in GitHub-pages, with simple commit and push.

In other words, I am hoping to wirte in my markdown file like this

```mermaid
graph LR
   A --> B
   A -->C
   C -->D
``` 

and add some js on my _layouts/post.html to somehow transform this to a mermaid graph.

I have found this theme claims that it supports such thing. But this theme looks way too heavy for me, the js were just too much, so I thought I could only use this file, which is simply

<script>
 window.Lazyload.js('{{ _sources.mermaid }}', function() {
   mermaid.initialize({
     startOnLoad: true
   });
   mermaid.init(undefined, '.language-mermaid');
 });
</script>

In my _include/mermaid.html, I replaced {{ _sources.mermaid }} to the mermaid cdn

<script>
 window.Lazyload.js('https://cdnjs.cloudflare.com/ajax/libs/mermaid/8.0.0/mermaid.min.js', function() {
   mermaid.initialize({
     startOnLoad: true
   });
   mermaid.init(undefined, '.language-mermaid');
 });
</script>

it still won't work. In my post, it was shown as regular code blocks, not a mermaid diagram.

Edit: In chrome developer's view, I don't see any connections made to the link https://cdnjs.cloudflare.com/ajax/libs/mermaid/8.0.0/mermaid.min.js.

And I tried this code, a connection to mermaid wes made in network tag in developer view, but the mermaid diagram still doesn't work

<script src="https://cdnjs.cloudflare.com/ajax/libs/mermaid/8.0.0/mermaid.min.js"></script>
<script>
var config = {
    startOnReady:true,
    theme: 'forest',
    flowchart:{
            useMaxWidth:false,
            htmlLabels:true
        }
};
mermaid.initialize(config);
mermaid.init(undefined, '.language-mermaid');
</script>

8 Answers 8

12

I found the solution.

<!DOCTYPE html>
<html lang="en">
   <head>
	 <script src="https://cdnjs.cloudflare.com/ajax/libs/mermaid/8.0.0/mermaid.min.js"></script>
    </head>
	 
<body>
 <pre><code class="language-mermaid">graph LR
A--&gt;B
</code></pre>

<div class="mermaid">graph LR
A--&gt;B
</div>
	
</body>
<script>
var config = {
    startOnLoad:true,
    theme: 'forest',
    flowchart:{
            useMaxWidth:false,
            htmlLabels:true
        }
};
mermaid.initialize(config);
window.mermaid.init(undefined, document.querySelectorAll('.language-mermaid'));
</script>

</html>

4
  • 1
    how do you run html codes on github, i dont think that is possible?
    – Firesh
    Jun 22, 2021 at 8:58
  • 1
    You can render your GitHub hosted Markdown files as HTML pages using GitHub Pages (pages.github.com), which is what the original question was about. You can add custom JavaScript, CSS, HTML etc.
    – jonasbn
    Feb 23, 2022 at 12:34
  • For GitHub, see: Include diagrams in your Markdown files with Mermaid and mermaid-js's README.
    – kenorb
    Jul 21, 2022 at 14:44
  • @wooohooo's solution works well and requires minimal configuration setup. Notice for default Github Pages, it actually uses a theme: github.com/pages-themes/primer. All you need is to copy and create _layouts/default.html and put in the two corresponding <script> sections. The <pre><code class="language-mermaid"></code></pre> part is handled automatically by Github Pages action. Oct 13 at 16:33
3

I solved it buy installing Github Mermaid extensioin in the browser. Actually, they have support for Chrome, Opera & Firefox.

I am using Chrome: https://chrome.google.com/webstore/detail/github-%20-mermaid/goiiopgdnkogdbjmncgedmgpoajilohe?hl=en

enter image description here

3

Feb. 2022: Markdown pages support Mermaid (gist too) (aug. 2022: wiki pages too).
As Jegors Čemisovs adds in the comments, this does not apply yet to GitHub pages, as illustrated by his example site.

See:

Include diagrams in your Markdown files with Mermaid

Mermaid is a JavaScript based diagramming and charting tool that takes Markdown-inspired text definitions and creates diagrams dynamically in the browser. Maintained by Knut Sveidqvist, it supports a bunch of different common diagram types for software projects, including flowcharts, UML, Git graphs, user journey diagrams, and even the dreaded Gantt chart.

Working with Knut and also the wider community at CommonMark, we’ve rolled out a change that will allow you to create graphs inline using Mermaid syntax:

Example

3
  • 3
    GitHub shows it in README.md file but doesn’t show on generated GitHub pages. The test repository: github.com/rabestro/test-mermaid The generated GitHub pages site: rabestro.github.io/test-mermaid Feb 16, 2022 at 8:43
  • 3
    @JegorsČemisovs Good point. I hope they will extend the support to GitHub generated pages.
    – VonC
    Feb 16, 2022 at 8:44
  • 3
    @JegorsČemisovs I have included your caveat in the answer for more visibility.
    – VonC
    Feb 16, 2022 at 8:46
1

In addition to the other answer that mention the plugins. In a firm I work form asked to provide extention links to most supported browsers.

Here are the Mermaid extention that renders Mermaid on browser level, I have tested them all:

Mermaid diagram for documentation When you use mermaid to create diagrams in Gitlab, and in case the business moves with new Version Control provider like Github or Azure DevOps or others, in this case you need to install a browser plugins to make it possible to view the diagrams.

1

I assume this requirement is with Jekyll + Github Pages since Github Pages is mentioned.

There's plugins doing this, such as jekyll-spaceship. It supports a lot more rendering format.

In order to make the unsafe plugins works on Github Pages, you will need a Github Workflow Action jekyll-deploy-action.

BTW: The custom plugins (putting plugins in your _plugins folder) won't work with Github Pages, they are not the safe plugins. Github Pages locks the config to safe=true, even locally.

1
  • On June 2, 2022, I was able to work around this stupid "unsafe plugins" problem by using Netlify to host the rendered site instead of GitHub Pages...
    – Shawn Eary
    Jun 2, 2022 at 21:53
0

The URL you tried to use does not exist. This is a correct URL:

https://cdnjs.cloudflare.com/ajax/libs/mermaid/8.0.0/mermaid.min.js

5
  • sorry, I updated the link but the result is still not right.
    – wooohooo
    Dec 21, 2018 at 11:50
  • @waterliu is the code inside the function executing at all? Dec 21, 2018 at 12:23
  • sorry I have no idea what that means... I have little knowledge about js. I can only say that this is all the js in my post. No other <script> tags.
    – wooohooo
    Dec 21, 2018 at 12:27
  • @waterliu insert a command of debugger; as the first operation of the function of the code you have given. Open the dev tools of your browser and load your page. If the code inside the function is executed, then your code should jump right into it. In the dev tools in the Sources tab check your Javascript. Is it refreshed? Dec 21, 2018 at 12:30
  • Let us continue this discussion in chat.
    – wooohooo
    Dec 21, 2018 at 12:46
0

I was having a similar problem and ended up just going with a custom jekyll plugin. If you are able to use custom plugins, the following will replace the markdown code blocks for mermaid with elements.

Jekyll::Hooks.register :posts, :pre_render do |post, payload|
  docExt = post.extname.tr('.', '')
  # only process if we deal with a markdown file
  if payload['site']['markdown_ext'].include? docExt
    newContent = post.content.gsub(/```mermaid([^`]+?)```/, '<div class="mermaid">\1</div>')
    post.content = newContent
  end
end
-3

The new best answer is that GitHub now directly supports including diagrams in your markdown files with Mermaid!

https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/

2

Your Answer

Reminder: Answers generated by Artificial Intelligence tools are not allowed on Stack Overflow. Learn more

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.