Mermaid Diagrams

[marct83]

Mermaid docs should be working with the Material for Mkdocs version that is in the techdocs container but they do not.

https://squidfunk.github.io/mkdocs-material/reference/diagrams/

I have added to my mkdocs.yml:

    - pymdownx.superfences:
        custom_fences:
          - name: mermaid
            class: mermaid
            format: !!python/name:pymdownx.superfences.fence_code_format

I have this in my doc:

  erDiagram
  entitlement {
   bigInt id
   timestamp iat
   varchar identifier
   jsonb result_set
}

Loading

I see this in Backstage:

[alexhampu]

I have the same problem, this also happens with Markmap. When I remove techdocs-core from the plugins list, both work perfectly.

[alexhampu]

It looks like this might be also related to #128

[agentbellnorm]

The recommended way to use mermaid diagrams with TechDocs is to use the addon defined here: https://www.npmjs.com/package/backstage-plugin-techdocs-addon-mermaid.

Can you try that addon and let me know if it works for you?

One limitation is that it's not possible to preview using the techdocs-cli, but it will work when reading the docs in backstage.

[AlexeyRaga]

@agentbellnorm no, it does not work.

As soon as I add

plugins:
  - techdocs-core

diagrams are not getting rendered, and the following warnings start popping up:

/opt # mkdocs build
INFO    -  DeprecationWarning: warning_filter doesn't do anything since MkDocs 1.2 and will be removed soon. All messages on the `mkdocs` logger get
           counted automatically.
             File "/usr/local/lib/python3.8/site-packages/src/core.py", line 22, in <module>
               from mkdocs.utils import warning_filter
             File "/usr/local/lib/python3.8/site-packages/mkdocs/utils/__init__.py", line 453, in __getattr__
               warnings.warn(
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /opt/site
INFO    -  DeprecationWarning: Using the add method to register a processor or pattern is deprecated. Use the `register` method instead.
             File "/usr/local/lib/python3.8/site-packages/markdown_inline_graphviz.py", line 48, in extendMarkdown
               md.preprocessors.add('graphviz_block',
             File "/usr/local/lib/python3.8/site-packages/markdown/util.py", line 462, in add
               warnings.warn(
INFO    -  DeprecationWarning: The 'md_globals' parameter of 'markdown_inline_graphviz.InlineGraphvizExtension.extendMarkdown' is deprecated.
             File "/usr/local/lib/python3.8/site-packages/markdown/core.py", line 125, in registerExtensions
               ext._extendMarkdown(self)
             File "/usr/local/lib/python3.8/site-packages/markdown/extensions/__init__.py", line 82, in _extendMarkdown
               warnings.warn(
INFO    -  DeprecationWarning: 'version' is deprecated. Use '__version__' instead.
             File "/usr/local/lib/python3.8/site-packages/markdown/__init__.py", line 51, in __getattr__
               warnings.warn(
             File "/usr/local/lib/python3.8/site-packages/mdx_truly_sane_lists/__init__.py", line 1, in
               from .mdx_truly_sane_lists import makeExtension
INFO    -  DeprecationWarning: Using the add method to register a processor or pattern is deprecated. Use the `register` method instead.
             File "/usr/local/lib/python3.8/site-packages/markdown_inline_graphviz.py", line 48, in extendMarkdown
               md.preprocessors.add('graphviz_block',
             File "/usr/local/lib/python3.8/site-packages/markdown/util.py", line 462, in add
               warnings.warn(
INFO    -  DeprecationWarning: The 'md_globals' parameter of 'markdown_inline_graphviz.InlineGraphvizExtension.extendMarkdown' is deprecated.
             File "/usr/local/lib/python3.8/site-packages/markdown/core.py", line 125, in registerExtensions
               ext._extendMarkdown(self)
             File "/usr/local/lib/python3.8/site-packages/markdown/extensions/__init__.py", line 82, in _extendMarkdown
               warnings.warn(
INFO    -  Documentation built in 1.29 seconds

I cannot really remove the plugin either since techdocs-cli adds it to my mkdocs.yaml automatically :(

[AlexeyRaga]

Tracking it down: looks like the warnings have anything to do with the problem.
It is when pymdownx.extra is getting added to markdown_extensions the diagrams stop working.

[AlexeyRaga]

I narrowed it down to this: the order in which pymdownx.extra and pymdownx.superfences come to the config matter!

When pymdownx.superfences appears before extra then it doesn't work. It renders the diagram block incorrectly, just as a normal highlighted code, ignoring mermaid segment.

But when extra comes before any of the superfences are mentioned, it works. Which is super strange.

I tried to update my local core.py to register extra before any other pymdownx are registered, and it seems to work now.

Is t here a chance that you validate this approach and publish a new version @johnphilip283 @agentbellnorm ?

[AtebMT]

Hmmmm, trying the suggestion by @AlexeyRaga and changing a local copy of the core.py, regenerating the static site and loading that into a browser then the Mermaid graphs render correctly. But, this is still doesn't work when I publish that into AWS and view within Backstage, it still shows the markup rather than the diagram.

[AlexeyRaga]

@AtebMT It does render it locally but does not when in Backstage, right?

I have figured that now we need to add thing like

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format ''

to mkdocs.yaml

PLUS it looks like Backstage needs to be >1.2.

Which is my problem currently because it doesn't build after the upgrade due to bacstage-cli referencing the "wrong" reference of rollup as it seems (https://discord.com/channels/687207715902193673/1192065911901913199/1196226580234645566)

[HatboyWonder]

We are also facing the same issue. Serving mkdocs locally shows mermaid sections unrendered, leaving the plain code snippet.

I verified that this works when we remove:

plugins:
  - techdocs-core

and replace it with:

theme:
  name: material

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[gaiazov]

The recommended way to use mermaid diagrams with TechDocs is to use the addon defined here: https://www.npmjs.com/package/backstage-plugin-techdocs-addon-mermaid.

Can you try that addon and let me know if it works for you?

One limitation is that it's not possible to preview using the techdocs-cli, but it will work when reading the docs in backstage.

We are currently using kroki but were looking to switch to client-side mermaid. Having to run our own kroki service feels like overkill, and the container has CVEs that sometimes are not remediated quickly

[martina-equinix]

@PeaWarrior Is there anything special we need to do after upgrading to mkdocs-techdocs-core 1.4.2 to get mermaid diagrams working? I tried upgrading but I still can't see the diagram. The mkdocs config looks like this:

theme:
  name: material
  
markdown_extensions:
  - footnotes
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.details
  - toc:
      permalink: True
plugins:
  - search 

[PeaWarrior]

Hey @martina-equinix. You might need to add mermaid2 under plugins.

Unfortunately the fix only works if you're serving through mkdocs. If serving via Techdocs, the external JavaScript gets removed from the sanitizer for security reasons which is what mermaid relies on at run time.

Here is some ways to get around it. backstage/backstage#24568