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
}

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