Open marct83 opened 9 months ago
I have the same problem, this also happens with Markmap. When I remove techdocs-core from the plugins list, both work perfectly.
It looks like this might be also related to #128
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.
@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 :(
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.
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 ?
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.
@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)
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
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.
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
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:
I have this in my doc:
I see this in Backstage: