Syntax Error Due to Incorrect Generated HTML File

[trnaviwala]

Not sure if this issue is being faced by me or others as well. Mermaid diagrams won't render for me no matter what - I checked my formatting, syntax, etc, but kept getting the Syntax Error image.

After checking the generated HTML files, I saw the HTML code was generated as follows.

<pre><code class="mermaid">graph TD
  A[Client] --&gt; B[Load Balancer]
  B --&gt; C[Server01]
  B --&gt; D[Server02]
</code></pre>

As you can see, it shows up as <code> ... </code>. I manually changed it to <div>...</div> and the diagrams generated just fine.

<pre><div class="mermaid">graph TD
  A[Client] --&gt; B[Load Balancer]
  B --&gt; C[Server01]
  B --&gt; D[Server02]
</div></pre>

Running mkdocs build reverts it back to code and so syntax errors start occurring again.

Attaching my yml file for reference:

site_name: My Documentation
nav:
  - Home: index.md
  - Modules: modules.md
theme: readthedocs
plugins:
  - search
  - mermaid2
extra_javascript:
  - https://unpkg.com/mermaid/dist/mermaid.min.js
markdown_extensions:
  - admonition

[github-actions[bot]]

Thank you for your contribution! This is very appreciated.

[trnaviwala]

Update: I saw the issue with codehilite but I do not use that extension, although I use admonition. So do I have to additionally install superfences and add the code mentioned in docs?

[fralau]

Thanks. Which version of the mkdocs-mermaid2-plugin are you using?

[trnaviwala]

I am using mkdocs-mermaid2-plugin-0.4.1 and mkdocs version 1.1.2

[fralau]

This is strange... What did you use as source (markdown/mermaid2 code)?

Sometimes mermaid can be fussy about indentations.

[trnaviwala]

I am a n00b at this, so in all likelihood, there would be some error on my end.

I have installed both using pip (automatic method).

I have also tried to add/remove indentations, semi-colons, etc.

Let me try adding the superfences extension and see if that helps.

[fralau]

In principle there is no need for superfences.

I would need to see your markdown code for the diagram above, because there might be a little detail there?

[trnaviwala]

Sure, I have created a new md file with only this diagram for testing.

graph TD
  A[Client] --> B[Load Balancer]
  B --> C[Server01]
  B --> D[Server02]

[trnaviwala]

Update: I tried using the pymdownx.superfences extension with custom_fences and it works fine.

[fralau]

Wow. This is unsettling...

I tested your diagram on my side and it worked as is, both on Firefox and Safari...

This is the HTML code it produced:

     <pre><code class="mermaid">graph TD
  A[Client] --&gt; B[Load Balancer]
  B --&gt; C[Server01]
  B --&gt; D[Server02]
</code></pre>

Result:

BTW, did you try to hard-refresh your page on the browser? Sometimes that plays a role...

[trnaviwala]

I tried this on Chrome & new Edge on Windows, and gives me the syntax error is its code instead of div. I have tried hard refresh multiple times as well but got the same error PNG everytime.

[fralau]

Would you be able to upload your sample project on a zip file? I will test it on my platform.

[fralau]

What is the status on your side? Is the problem solved for you?

[fralau]

Unless there is feedback on this issue, it will be closed.

[mrRobot62]

Hi, unfortunately I have the same problem on my mac (10.15.6)

I tried it with under Anaconda (1.9.12) with Python 3.8, 3.7 and 3.6 - every time with the same result I used a totally brand new MkDocs project Problem occurs on Safari & Chrome

site_name: Mermaid-Test

nav:

• "Index": index.md

plugins:

• search
• mermaid2

and inside index.md

Mermaid

graph TD
A[Client] --> B[Load Balancer]
B --> C[Server01]
B --> D[Server02]

and get every time this syntax error.

Additional info: Out from html source code

<h1 id="mermaid">
  | Mermaid
  | </h1>
  | <pre><code class="mermaid">graph TD
  | A[Client] --&gt; B[Load Balancer]
  | B --&gt; C[Server01]
  | B --&gt; D[Server02]
  | </code></pre>

<script src="https://unpkg.com/mermaid@8.6.4/dist/mermaid.min.js"></script>

<script>
  | mermaid.initialize({});
  | </script>

[fralau]

@mrRobot62 Thanks a lot!

What would really be helpful at this point, is a full copy of your sample project, so that I could test it. Could you upload a zip?

[mrRobot62]

mermaid_test.zip

voi lá

[mrRobot62]

and thanks for this very very fast response. Hope you (we) can fix this issue, because I'm currently writing a a lot of docs with mermaid graphs inside :-O (I need them ;-) )

[mrRobot62]

maybe a help for you:

If I include in my MkDocs.yml file this:

markdown_extensions:
   - pymdownx.superfences

The result on the web-page is:

[fralau]

@mrRobot62 OK. What I can tell off the bat, is that you have two issues:

The first is that the plugin works with the material theme, not the original one.

theme: 
  name: material

Also, if you use superfences as a markdown extension, then of course the Mermaid diagram will not be displayed (since it is a plugin for highlighting source code)!

If you want to use superfences, you need ask it to "release" your mermaid code so that it is actually displayed as a diagram. You must declare a custom fence, see instructions.

The question remains, of why mermaid diagrams do not work with the default mkdocs theme? I don't know the answer, but it's worth investigating.

[mrRobot62]

ok, thanks for your response. SuperFences is not needed for my issue, so I will remove it.

Issue with other themes: mhm - Normally I want to use windmill Will try again with others - hope you can fix it with mermaid2.

Update 1: with your suggestion to change to material-theme it will work. Try to do the same with my "real" MkDocs project.

Thanks for your fast help

Update 2: With Windmill I have the same issue as before, no mermaid graphs will be created.

[fralau]

@mrRobot62 The interaction between the mermaid diagrams and themes is actually not managed by the plugin.

Perhaps @facelessuser (who has delt with those issues from the viewpoing of the pymdownx extensions, might be able to provide a quick explanation of why mermaid diagrams work easily in the material theme, but not in others?

[fralau]

@mrRobot62 How about that...

mermaid diagrams are properly displayed in the default theme and in windmill, providing you use superfences:

markdown_extensions:
   - pymdownx.superfences:
      # make exceptions to highlighting of code:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:mermaid2.fence_mermaid

I tested it and it works.

So the current situation is that the minimalist configuration of the mermaid2 plugin works only with the material theme (I am not sure why, for the moment).

[kerrerain]

Hi, I have the same problem. I'm using the material theme (https://github.com/squidfunk/mkdocs-material). I just wanted you to know that I was looking at this problem too. I'm going to dive into the source code of the plugin to better understand the issue.

[fralau]

@kerrerain Thanks a lot. Here is the current situation:

1. By default, the plugin works with the material theme.
2. To make it work with another theme, use superfences with custom fences (see new explanation in the documentation).

[fralau]

@kerrerain and @mrRobot62 If you are using superfences, it is important to follow the instructions to the letter.

In general, I strongly suggest that you follow the Troubleshooting steps.

[kerrerain]

I don't know much of mkdocs, but it is related to the default syntax highlighter indeed, as you noticed. Here is my understanding of the issue so far:

If I add this code block to the markdown template:

```mermaid classDiagram class Tag { } ```

Then I get this error from mermaid.js:

Expecting 'open_directive', 'CLASS', 'ANNOTATION_START', 'MEMBER', 'SEPARATOR', 'CALLBACK', 'LINK', 'CSSCLASS', 'UNICODE_TEXT', 'NUM', 'ALPHA', got 'DEPENDENCY'"
"classDiagram
  <span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">Tag</span> {</span>
  }"

I suppose that this is the default highlighter from mkdocs that renders this code block first. That's why Mermaid.js fails to parse this.

Superfences isn't the only highlighter available, I suppose. The solution would be to disable the syntax highlighter for the "mermaid" code block, as you did. I Suppose that in my case, this is not "superfences" that is used by default -- I don't known exactly what it is for the moment, to be honest.

[mrRobot62]

@fralau : thanks for your suggestions, will do this in the next days - currently I have not enough time :-O

[kerrerain]

Here is the project I used to test this behavior:

mkdocs-test.zip

I'm running python 3.7.7 on windows. I created a virtualenv for this test, where I installed mkdocs. I cloned the repository mkdocs-mermaid2-plugin and ran "pip install -e ." at the root of the mkdocs-mermaid2-plugin folder.

[mrRobot62]

@kerrerain : I believe your mermaid code is inconsistent.

I did it on my system with your code - and got an error -

Did the same with an example from mermaid live editor, insert it in my file and

[mrRobot62]

And now with your example (extended ;-))

classDiagram
    class Tag {
        +String name
        +int day
    }
    class Woche {
        +int week
    }

    Woche <|-- Tag

Update 1: Problem in your code is missing indentation

classDiagram
class Tag {
}

produce the error

But this

classDiagram
   class Tag {
   }

should work

[fralau]

@kerrerain Indeed, your index.md file does not make sense.

In your markdown file, there should be a description of the diagram in mermaid syntax. This file should not contain any javascript code.

[mrRobot62]

@kerrerain : classes without any attributes inside should work without any problems, depends on what you want "to explain"

[kerrerain]

@fralau @mrRobot62 Thank you both for your feedbacks.

The inconsistent syntax would be the sweetest explanation :) However, I copy-pasted my own code from the Mermaid live editor, where it renders without a syntax error.

I also copy-pasted the several code blocks that @mrRobot62 provided, but without much success. Thank you anyway for the effort, much appreciated :D

There is no javascript in the index.md file I provided. This javascript is added by the syntax highlighter of mkdocs: highlight.js. To prove this statement: if I add this block to the mkdocs.yml configuration file:

theme:
  name: mkdocs
  highlightjs: false

... Then the index.md file I provided renders without a syntax error.

If I set the highlightjs property back to "true" or if I remove it from the configuration, then I got the syntax error back.

[mrRobot62]

@kerrerain I checked it with YOUR code - and - bam - error

checked MkDocs.yml file tataaa: found the problem

try this:

site_name: Issue 11 of mkdocs-mermaid2-plugin
site_author: kerrerain
copyright: Copyright kerrerain, © 2020

theme:
   name: material
nav:
  - Home: index.md

plugins:
  - search
  - mermaid2:
      version: 8.7.0

IMPORTANT Your have to install before: pip install mkdocs-material

and than :

[kerrerain]

@mrRobot62 Yes, I confirm that behavior, thanks ;)

At least I might have provided some insight about how a new user can behave with the plugin. It might help to improve the documentation, even If you have already changed it @fralau

Edit: I also confirm that with the default theme, this block:

markdown_extensions:
  - pymdownx.superfences:
      # make exceptions to highlighting of code:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:mermaid2.fence_mermaid

... Allows to render the mermaid diagram. So the section you added to the documentation may help the users.

[fralau]

@kerrerain Thanks for your feedback, and I am glad the documentation update could be of help.

@mrRobot62 Thanks a lot for your contribution in advancing this issue.

What is the status now? Is there still something unsolved, or should we close the issue?

[kerrerain]

@fralau It depends on the effort we want to spend on this behavior.

As a user, it might feel easier to not bother with the pymdownx.superfences block in the configuration file. I don't know. There might be another easier solution. For the moment, as long as it is mentioned in the documentation, there's a working solution available. So, this very issue is solved but there might be an improvement possible.

[fralau]

This is understood: I will close this issue because the immediate concern ("bug") was solved by a workaround (use superfences + custom fences).

I opened an new issue (#16) for the enhancement request (to make the default configuration work with most themes).