fralau / mkdocs-mermaid2-plugin

A Mermaid graphs plugin for mkdocs
https://mkdocs-mermaid2.readthedocs.io
MIT License
214 stars 26 forks source link

Superfences custom fence function does not seem to work #77

Closed THENATHE closed 1 year ago

THENATHE commented 1 year ago

Running current version of mkdocs, installed yesterday. Using superfences, and added the declaration so it loads.

Nothing at all shows up if I use mermaid version 10.0.2. If I swap to ANY OTHER VERSION (tried 8.7.0, 8.8.0, and 10.2.4) I get a syntax error, despite trying the code in the online editor with success. I even tried to use the example diagram right off this github readme and it still errors. Any ideas?

github-actions[bot] commented 1 year ago

Thank you for your contribution! This is very appreciated.

fralau commented 1 year ago

Thanks. Possibly a configuration problem?

Make sure you have the latest version of mkdocs-mermaid2 (use pip install --upgrade).

You would need to give at least the relevant info from the config file (mkdocs.yaml), and the relevant part from the markdown page, plus the error messages and any other info that could give an idea.

THENATHE commented 1 year ago

Mermaid is fully up to date

Relevant config lines look like the following

plugins:
  - search
  - mermaid2:
      version: 10.2.4
      arguments:
        theme: default
        securityLevel: 'loose'

markdown_extensions:
  - attr_list
  #- pymdownx.highlight:
   #   anchor_linenums: true
  - pymdownx.superfences:
       custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:mermaid2.fence_mermaid_custom
  #- pymdownx.inlinehilite
  #- pymdownx.keys
  - pymdownx.tasklist:
      custom_checkbox: true
  #- pymdownx.tabbed:
   #   alternate_style: true
  - admonition

I have also tried removing the commented lines instead of just commenting them out, no dice there

markdown page


```mermaid
graph LR
    hello --> world
    world --> again
    again --> hello

The only error message I am getting is the generic "Syntax error in text" bomb message, no errors in console. 
fralau commented 1 year ago

At least it means the html calls the javascript code for interpreting mermaid schemas.

I do not see anything strange.

THENATHE commented 1 year ago

Python 3.10.6, mkdocs 1.4.3, macros 1.0.2 Yes, I started out without any arguments because I have a tendency to get something working and then mess with it to my liking, but it not working brought me to those arguments just to see. I have removed them just now and nothing different occurred. I cannot use mkdocs serve because I am currently running a live multi-site apache install and this is going into a little side project.

Here is the mkdocs build output if that helps at all (note, I replaced some stuff in the output with [redacted]

DEBUG    -  Loading configuration file: /var/www/[redacted]/mkdocs.yml
DEBUG    -  Loaded theme configuration for 'cinder' from
            '/home/ubuntu/.local/lib/python3.10/site-packages/cinder/mkdocs_theme.yml': {'cinder_theme': True,
            'static_templates': ['404.html'], 'include_search_page': False, 'search_index_only': False, 'shortcuts':
            {'help': 191, 'next': 78, 'previous': 80, 'search': 83}}
DEBUG    -  Config value 'config_file_path' = '/var/www/[redacted]/mkdocs.yml'
DEBUG    -  Config value 'site_name' = '[redacted] Family Archive'
DEBUG    -  Config value 'nav' = [{'About': 'about.md'}, {'Member Areas': '/members/'}, {'Current Events/Announcements':
            'announcements.md'}, {'Contact': 'contact.md'}]
DEBUG    -  Config value 'pages' = None
DEBUG    -  Config value 'site_url' = 'https://[redacted]/'
DEBUG    -  Config value 'site_description' = '[redacted] Family Archive!'
DEBUG    -  Config value 'site_author' = 'THENATHE'
DEBUG    -  Config value 'theme' = Theme(name='cinder', dirs=['/home/ubuntu/.local/lib/python3.10/site-packages/cinder',
            '/home/ubuntu/.local/lib/python3.10/site-packages/mkdocs/templates'], static_templates=['404.html',
            'sitemap.xml'], name='cinder', locale=Locale('en'), cinder_theme=True, include_search_page=False,
            search_index_only=False, shortcuts={'help': 191, 'next': 78, 'previous': 80, 'search': 83},
            highlightjs=True, colorscheme='dracula', hljs_languages=['yaml', 'bash', 'shell', 'javascript',
            'typescript', 'php', 'xml', 'css', 'scss', 'python', 'cs', 'markdown'])
DEBUG    -  Config value 'docs_dir' = '/var/www/[redacted]/docs'
DEBUG    -  Config value 'site_dir' = '/var/www/[redacted]/site'
DEBUG    -  Config value 'copyright' = None
DEBUG    -  Config value 'google_analytics' = None
DEBUG    -  Config value 'dev_addr' = _IpAddressValue(host='127.0.0.1', port=8000)
DEBUG    -  Config value 'use_directory_urls' = True
DEBUG    -  Config value 'repo_url' = None
DEBUG    -  Config value 'repo_name' = None
DEBUG    -  Config value 'edit_uri_template' = None
DEBUG    -  Config value 'edit_uri' = None
DEBUG    -  Config value 'extra_css' = ['css/custom.css']
DEBUG    -  Config value 'extra_javascript' = ['js/emoji++.js']
DEBUG    -  Config value 'extra_templates' = []
DEBUG    -  Config value 'markdown_extensions' = ['toc', 'tables', 'fenced_code', 'attr_list', 'pymdownx.superfences',
            'pymdownx.tasklist', 'admonition']
DEBUG    -  Config value 'mdx_configs' = {'pymdownx.superfences': {'custom_fences': [{'name': 'mermaid', 'class':
            'mermaid', 'format': functools.partial(<function fence_mermaid at 0xffffa80e11b0>, custom=True)}]},
            'pymdownx.tasklist': {'custom_checkbox': True}}
DEBUG    -  Config value 'strict' = False
DEBUG    -  Config value 'remote_branch' = 'gh-pages'
DEBUG    -  Config value 'remote_name' = 'origin'
DEBUG    -  Config value 'extra' = {'analytics': {'provider': 'google', 'property': 'G-XXXXXXXXXX'}}
DEBUG    -  Config value 'plugins' = {'search': <mkdocs.contrib.search.SearchPlugin object at 0xffffa7f6f670>,
            'mermaid2': <mermaid2.plugin.MarkdownMermaidPlugin object at 0xffffa7f6f910>, 'macros':
            <mkdocs_macros.plugin.MacrosPlugin object at 0xffffa531b040>}
DEBUG    -  Config value 'hooks' = {}
DEBUG    -  Config value 'watch' = []
DEBUG    -  Running 3 `config` events
INFO     -  MERMAID2  - Initialization arguments: {'theme': 'default', 'securityLevel': 'loose'}
INFO     -  MERMAID2  - Using javascript library (10.2.4):
               https://unpkg.com/mermaid@10.2.4/dist/mermaid.esm.min.mjs
INFO     -  [macros] - Macros arguments: {'module_name': 'main', 'modules': [], 'render_by_default': True,
            'include_dir': '', 'include_yaml': [], 'j2_block_start_string': '', 'j2_block_end_string': '',
            'j2_variable_start_string': '', 'j2_variable_end_string': '', 'on_undefined': 'keep', 'on_error_fail':
            False, 'verbose': False}
DEBUG    -  [macros] - Project dir '/var/www/[redacted]'
DEBUG    -  [macros] - Variables: ['extra', 'config', 'environment', 'plugin', 'git', 'analytics']
INFO     -  [macros] - Extra variables (config file): ['analytics']
DEBUG    -  [macros] - Content of extra variables (config file): {'analytics': {'provider': 'google',
            'property': 'G-XXXXXXXXXX'}}
INFO     -  [macros] - Extra filters (module): ['pretty']
DEBUG    -  [macros] - Docs directory: /var/www/[redacted]/docs
DEBUG    -  [macros] - Includes directory: /var/www/[redacted]/docs
DEBUG    -  [macros] - Undefined behavior: <class 'jinja2.runtime.DebugUndefined'>
DEBUG    -  Running 1 `pre_build` events
INFO     -  Cleaning site directory
INFO     -  Building documentation to directory: /var/www/[redacted]/site
DEBUG    -  Looking for translations for locale 'en'
DEBUG    -  No translations found here:
            '/home/ubuntu/.local/lib/python3.10/site-packages/mkdocs/contrib/search/templates/locales'
DEBUG    -  No translations found here: '/home/ubuntu/.local/lib/python3.10/site-packages/mkdocs/templates/locales'
DEBUG    -  No translations found here: '/home/ubuntu/.local/lib/python3.10/site-packages/cinder/locales'
INFO     -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
              - index.md
              - members/index.md
WARNING  -  A relative path to 'about.md' is included in the 'nav' configuration, which is not found in the
            documentation files
DEBUG    -  An absolute path to '/members/' is included in the 'nav' configuration, which presumably points to an
            external resource.
WARNING  -  A relative path to 'announcements.md' is included in the 'nav' configuration, which is not found in the
            documentation files
DEBUG    -  Running 1 `nav` events
DEBUG    -  Reading markdown pages.
DEBUG    -  Reading: index.md
DEBUG    -  Running 1 `page_markdown` events
DEBUG    -  Reading: contact.md
DEBUG    -  Running 1 `page_markdown` events
DEBUG    -  Reading: members/index.md
DEBUG    -  Running 1 `page_markdown` events
DEBUG    -  Copying static assets.
DEBUG    -  Copying media file: 'snow.php'
DEBUG    -  Copying media file: 'audio/Grandpa Ted Part 1.flac'
DEBUG    -  Copying media file: 'audio/Grandpa Ted Part 2.flac'
DEBUG    -  Copying media file: 'css/ProductSans-Regular.woff'
DEBUG    -  Copying media file: 'css/custom.css'
DEBUG    -  Copying media file: 'img/computer.svg'
DEBUG    -  Copying media file: 'img/favicon.ico'
DEBUG    -  Copying media file: 'img/logo.svg'
DEBUG    -  Copying media file: 'img/party-blob.gif'
DEBUG    -  Copying media file: 'js/discordwidget.html'
DEBUG    -  Copying media file: 'js/emoji++.js'
DEBUG    -  Copying media file: 'css/base.css'
DEBUG    -  Copying media file: 'css/base.min.css'
DEBUG    -  Copying media file: 'css/bootstrap-custom.css'
DEBUG    -  Copying media file: 'css/bootstrap-custom.min.css'
DEBUG    -  Copying media file: 'css/cinder.css'
DEBUG    -  Copying media file: 'css/cinder.min.css'
DEBUG    -  Copying media file: 'css/highlight.css'
DEBUG    -  Copying media file: 'css/highlight.min.css'
DEBUG    -  Copying media file: 'fonts/fontawesome-webfont.eot'
DEBUG    -  Copying media file: 'fonts/fontawesome-webfont.svg'
DEBUG    -  Copying media file: 'fonts/fontawesome-webfont.ttf'
DEBUG    -  Copying media file: 'fonts/fontawesome-webfont.woff'
DEBUG    -  Copying media file: 'img/grid1.png'
DEBUG    -  Copying media file: 'img/grid10.png'
DEBUG    -  Copying media file: 'img/grid11.png'
DEBUG    -  Copying media file: 'img/grid12.png'
DEBUG    -  Copying media file: 'img/grid13.png'
DEBUG    -  Copying media file: 'img/grid14.png'
DEBUG    -  Copying media file: 'img/grid15.png'
DEBUG    -  Copying media file: 'img/grid16.png'
DEBUG    -  Copying media file: 'img/grid17.png'
DEBUG    -  Copying media file: 'img/grid18.png'
DEBUG    -  Copying media file: 'img/grid19.png'
DEBUG    -  Copying media file: 'img/grid2.png'
DEBUG    -  Copying media file: 'img/grid20.png'
DEBUG    -  Copying media file: 'img/grid3.png'
DEBUG    -  Copying media file: 'img/grid4.png'
DEBUG    -  Copying media file: 'img/grid5.png'
DEBUG    -  Copying media file: 'img/grid6.png'
DEBUG    -  Copying media file: 'img/grid7.png'
DEBUG    -  Copying media file: 'img/grid8.png'
DEBUG    -  Copying media file: 'img/grid9.png'
DEBUG    -  Copying media file: 'js/base.js'
DEBUG    -  Copying media file: 'js/bootstrap-3.0.3.min.js'
DEBUG    -  Copying media file: 'js/highlight.pack.js'
DEBUG    -  Copying media file: 'search/lunr.js'
DEBUG    -  Copying media file: 'search/main.js'
DEBUG    -  Copying media file: 'search/worker.js'
DEBUG    -  Building theme template: 404.html
DEBUG    -  Building theme template: sitemap.xml
DEBUG    -  Gzipping template: sitemap.xml
DEBUG    -  Building markdown pages.
DEBUG    -  Building page index.md
DEBUG    -  Running 1 `page_context` events
DEBUG    -  Running 1 `post_page` events
DEBUG    -  Building page contact.md
DEBUG    -  Running 1 `page_context` events
DEBUG    -  Running 1 `post_page` events
DEBUG    -  Building page members/index.md
DEBUG    -  Running 1 `page_context` events
DEBUG    -  Running 1 `post_page` events
INFO     -  MERMAID2  - Found superfences config: {'custom_fences': [{'name': 'mermaid', 'class': 'mermaid', 'format':
            functools.partial(<function fence_mermaid at 0xffffa80e11b0>, custom=True)}]}
INFO     -  MERMAID2  - Found 'fence_mermaid_custom' function: activate custom loader for superfences
INFO     -  MERMAID2  - Custom loader activated
INFO     -  MERMAID2  - Page '[redacted] Family Member Index': found 2 diagrams, adding scripts
INFO     -  MERMAID2  - Adding call to script for version10.2.4.
DEBUG    -  Running 2 `post_build` events
INFO     -  Documentation built in 0.69 seconds
fralau commented 1 year ago

It is bizarre, because I tested the same diagram on 10.2.4 and 10.1.1, and it works. 🤔

In the repository, I updated the /test/medium test case. Can you run it on your installation, and tell me what happpens on the page called "second"?

Screen capture

THENATHE commented 1 year ago

Looks like it is failing because of lack of material theme, as it worked with the example 'medium' you gave me, and I changed just the theme to cinder and it began failing again. I also tried using mkdocs without a theme and it still failing. Material-theme isn't a requirement, is it?

fralau commented 1 year ago

That's an interesting question 🤔. My own doc declares that the plugin is compatible with the default, material and windmill themes. I haven't tested recently though.

If there was something wrong, I would have a look at the handling of fences.

THENATHE commented 1 year ago

I can confirm that on my machine it worked with only the material theme. I did not try windmill, but it is breaking because of cinder theme and default theme, but all other settings unchanged it works on the material theme.

I would love if you could get this working, I plan on using it to make a family tree that is updatable 😄 Let me know if you would like me to do any additional testing

fralau commented 1 year ago

Thanks for you help offer! If you test the simple test case, which uses the default template, you will see that it works out of the box.

~It seems that the Superfences extension is needed (and works) for the Material theme only.~

Can you check that you can make it work with loose?

fralau commented 1 year ago

@THENATHE Thanks for you help offer!

Now I got it straight.

The Superfences extension is needed only if you want syntax highlighting.

If you test the simple test case, which uses the default template, you will see that it works out of the box. It will also work if you set the theme to Material.

If you really want to use the Superfences extension, there are two custom_fences function:

Here is the why of your issue: You were using the Material fence function (custom), instead of the standard one for the default themes.

Solution: remove the _custom suffix; or remove altogether the Superfences extensions, if you don't want any syntax highlighting.

THENATHE commented 1 year ago

Apologies that it took so long for me to get back to you on this, but your solution does indeed work on the cinder theme. Thank you very much for your help!

libukai commented 1 year ago

I encountered a strange issue where the default fence_mermaid_custom in Material 9.4.3 theme is not working. I can only make it work by modifying it to fence_mermaid.

nablabits commented 4 months ago

I encountered a strange issue where the default fence_mermaid_custom in Material 9.4.3 theme is not working. I can only make it work by modifying it to fence_mermaid.

Just in case this helps to someone else. I hit this same problem with my version of material which was quite outdated 7.3.3

Upgrading to these two versions worked for me:

mkdocs-material==9.5.25
mkdocs-material-extensions==1.3.1