CODEWITHSUNDEEP
javascriptjekyllgithub-pagesmermaid
wooohooo
wooohooo

Reputation: 636

How to make GitHub Pages Markdown support mermaid diagram?

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>

Upvotes: 18

Views: 18519

Answers (12)

mtrakal
mtrakal

Reputation: 6417

In 2024, you can use most simple solution:

  • create in root of your git repo / project file: _includes/head-custom.html
  • include just content of:
<script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
    mermaid.initialize({startOnLoad:true,theme:'neutral'})
    await mermaid.run({querySelector:'code.language-mermaid'})
</script>

The _includes/head-custom.html content will be placed inside html head block.

So script will:

  • import mermaid version 11 (latest when I wrote this post. So check if there is new version on official mermaind page)
  • initialize mermaid on page is loaded
  • apply mermaind on code block used as ```mermaid in markdown source.

Upvotes: 0

Developer Sheldon
Developer Sheldon

Reputation: 2160

I faced a very special issue that the deployed post keeps compaining the syntax is wrong. what works for me is to add ";" at the end of each line. I'm guessing what ends happening is that somehow my post page is compacted into one line when deploying happenings. After adding ";" to each line, the graphs end up rendering perfectly

Upvotes: 0

adnan
adnan

Reputation: 1

I wanted this to work out of the box. Just listing my markdown files in a subfolder named docs, pointing gh-pages to deploy at everypush to the main branch using the files in docs. This is very much doable also in actions, but it is less hassle here.

I have managed to make it work by adding the mermaid js script in a newly created _layouts folder.

mkdir docs/_layouts
touch docs/_layouts/mermaid.html
nano docs/_layouts/mermaid.html

And adding the following:

<script src="https://unpkg.com/[email protected]/dist/mermaid.min.js"></script>
<script>
  document.addEventListener('DOMContentLoaded', () => {
    mermaid.initialize({ startOnLoad: true });
  });
</script>

Then in each markdown file I want to render mermaid in I add the following line {% include mermaid.html %} at the top after the header :

---
title:  "MyTitle"
layout: MyLayout
---

{% include mermaid.html %}


# MyTitle

This will make it render with no github actions and with any theme.

Upvotes: 0

Bruce Tong
Bruce Tong

Reputation: 1431

i've opted to use html instead of markdown language. Using examples from wooohooo, Mermaid's site, and stackoverflow

header html in my post.md

enclose your mermaid code inside div tags with mermaid class attribute

sequenceDiagram
    participant Alice
    participant Bob
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts 
prevail...
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!

in the header of the default layout template

<script src="https://cdnjs.cloudflare.com/ajax/libs/mermaid/10.6.1/mermaid.min.js"></script>

after html body of the default layout template

window.addEventListener('DOMContentLoaded', function(){
           var config = {
                startOnLoad:true,
                htmlLabels:true,
                callback:function(id){
                    console.log(id,' rendered');
                },
                flowchart:{
                        useMaxWidth:false,
                    }
            };
            
            mermaid.initialize(config);
        },false);

Upvotes: 0

VonC
VonC

Reputation: 1324935

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

Upvotes: 3

groovecoder
groovecoder

Reputation: 1581

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/

Upvotes: -3

alex
alex

Reputation: 929

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.

Upvotes: 1

Maytham Fahmi
Maytham Fahmi

Reputation: 33407

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.

Upvotes: 1

Hafed Gabroun
Hafed Gabroun

Reputation: 57

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

Upvotes: 3

harper357
harper357

Reputation: 101

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

Upvotes: 0

wooohooo
wooohooo

Reputation: 636

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>

Upvotes: 14

Lajos Arpad
Lajos Arpad

Reputation: 76601

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

Upvotes: 0

Related Questions