[TechDocs] - Support Mermaid Diagrams Using the Addon Framework

[nmatare]

Expected Behavior

Expecting techdocs/backstage to render custom JS / mermaid plugin.

Current Behavior

mkdocs/techdocs is not rendering custom JS / mermaid plugin; instead only the raw instructions are presented

Context

I'm running a custom tech-docs backend with the mermaid extension installed in the local container. For example:

Tech-docs custom container:

...
pip install --quiet \
    mkdocs==1.1.2 \
    cookiecutter==1.7.2 \
    Markdown==3.2.2 \
    pygments==2.6.1 \
    mkdocs-material \
    mkdocs-jupyter \
    mkdocs-mermaid2-plugin \
   ...

Your Environment

mkdocs-techdocs-core 0.0.13
mkdocs-plugin-mermaid 0.1.1

My mkdocs.yml config:

plugins:
  - techdocs-core
  - mermaid2

extra_javascript:
  - https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-MML-AM_CHTML
  - https://unpkg.com/mermaid/dist/mermaid.min.js

[OrkoHunter]

We'll look more into the MkDocs mermaid2 plugin more to see how we can make it work with TechDocs.

But TechDocs loading an external Javascript from its storage and executing it, will be a security threat for a Backstage app. Hence, TechDocs is only allowed to import HTML and CSS.

One possible approach would be to make the files under extra_javascript available in Backstage/TechDocs frontend; and then when the mermaid diagram's HTML is rendered, it would work as expected. But I'm not too sure.

[stale]

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.

[nmatare]

Don't think this should get closed...

@OrkoHunter

[OrkoHunter]

Re-opening then! Also cc @backstage/techdocs-core

[nmatare]

Thanks Orko!

[kuangp]

I want to report a similar limitation when trying to use MathJax with the python-markdown-math extension. I am able to include the necessary scripts as part of the Backstage frontend but MathJax inserts special <script type="math/tex"> tags into the docs to render its math statements. It looks like Techdocs sanitizes the generated HTML through its transformers:

backstage/plugins/techdocs/src/reader/transformers/sanitizeDOM/index.ts

Lines 25 to 31 in 4eb2729

	export const sanitizeDOM = (): Transformer => {
	return dom => {
	const sanitizedHtml = sanitizeHtml(dom.innerHTML, {
	allowedTags: TECHDOCS_ALLOWED_TAGS,
	allowedAttributes: TECHDOCS_ALLOWED_ATTRIBUTES,
	allowedSchemes: ['http', 'https', 'ftp', 'mailto', 'data', 'blob'],
	});

Is it possible to support whitelisting math/tex type script tags? It looks like santizeHTML should be capable of allowing this through its exclusiveFilter config.

Let me know if I should open a separate issue for this.

[stale]

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.

[dtuite]

@OrkoHunter What is the concern with "TechDocs loading an external Javascript from its storage and executing it"? Isn't that what most Backstage plugins do? I'm not an engineer so I'm probably not understanding something sensible 😊

[kuangp]

@OrkoHunter What is the concern with "TechDocs loading an external Javascript from its storage and executing it"? Isn't that what most Backstage plugins do? I'm not an engineer so I'm probably not understanding something sensible 😊

My understanding is that this will enable regular users to include external JS as part of their TechDocs site, opening the risk for anyone to potentially run malicious JS within Backstage. Plugins OTOH are installed explicitly by the Backstage integrators/admins allowing them to audit them to ensure they are safe to run.

[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.

[iamEAP]

Hmm... The should be. Are you on the latest release?

Ping @camilaibs, do you remember seeing any issues with Addons when working on this? #11542

[camilaibs]

Hmm... The should be. Are you on the latest release?

Ping @camilaibs, do you remember seeing any issues with Addons when working on this? #11542

@johanneswuerbach you have to register addons in EntityPage otherwise they won't render.

For example:

packages/app/src/components/catalog/EntityPage.tsx

import { TechDocsAddons } from '@backstage/plugin-techdocs-react';
import {
  ReportIssue,
  TextSize,
} from '@backstage/plugin-techdocs-module-addons-contrib';

// ...

<EntityLayout.Route path="/docs" title="Docs">
+ <EntityTechdocsContent>
+    <TechDocsAddons>
+     <TextSize />
+     <ReportIssue />
+    </TechDocsAddons>
+  </EntityTechdocsContent>
</EntityLayout.Route>

I tested it on the master branch and the TextSize and ReportIssue addons are rendering on the EntityDocs page:

TextSize	ReportIssue

[johanneswuerbach]

I've tried this master...johanneswuerbach:techdocs-mermaid, but I don't see my component being called 🤔 , it works without problems in the docs section.

[dmckernanacv]

@camilaibs I am seeing inconsistent behavior with the Addons as well.

TextSize and ExpandNavigation work but only on the initial page of the Content view, they both work throughout the Docs view though

After capturing those screenshots I also confirmed the same behavior happens with the Mermaid addon, it only works on the initial page of the TechDoc, but all addons seem to go missing when navigating away from that initial page. (on the Content view only, NOT the Docs view)

[camilaibs]

@camilaibs I am seeing inconsistent behavior with the Addons as well.

TextSize and ExpandNavigation work but only on the initial page of the Content view, they both work throughout the Docs view though

After capturing those screenshots I also confirmed the same behavior happens with the Mermaid addon, it only works on the initial page of the TechDoc, but all addons seem to go missing when navigating away from that initial page. (on the Content view only, NOT the Docs view)

We have an open pull request fixing the addons in the catalog subpages, thanks for reporting: #11609

[johanneswuerbach]

Unrelated to this, is there already a way to include tech-docs addons in techdocs-cli serve?

[iamEAP]

Unrelated to this, is there already a way to include tech-docs addons in techdocs-cli serve?

Would love to hear proposals on how to make this work; a separate issue for this would be a great place to start.

[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.

[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.

[vonjones]

I noticed this support for Mermaid in Material for Mkdocs 8.2.0. I think could mean that bumping the mkdocs-material version from 8.1.1 to 8.2.0 here and adding the mermaid config from that page to the existing superfences config may pick up support.

[KeesCBakker]

@vonjones did you ever get it to work with the 8.2.0 version?

[vonjones]

We did not attempt this approach. Instead, we are using the backstage-plugin-techdocs-addon-mermaid plugin. It's working for the most part. The issues I'm seeing are:

1. Styling with the default dark mode theme is bad, since the black lines in the diagram don't show up on the dark background. We do see that it renders correctly if you change <div class="mermaid"> to <div class="mermaid" style="background-color: white"> in the browser, but have not made a code change to fix it yet. This seems like a 'bug" with the plugin.
2. It does not support the ability to use mkdocs serve to view your output locally. So for developers who do not use something like VScode with a preview function, it makes it hard for developers to see their diagram as they build, prior to merge. I think this would be the case with all plugin-based approaches.

[dmckernanacv]

We did not attempt this approach. Instead, we are using the backstage-plugin-techdocs-addon-mermaid plugin. It's working for the most part. The issues I'm seeing are:

1. Styling with the default dark mode theme is bad, since the black lines in the diagram don't show up on the dark background. We do see that it renders correctly if you change <div class="mermaid"> to <div class="mermaid" style="background-color: white"> in the browser, but have not made a code change to fix it yet. This seems like a 'bug" with the plugin.
2. It does not support the ability to use mkdocs serve to view your output locally. So for developers who do not use something like VScode with a preview function, it makes it hard for developers to see their diagram as they build, prior to merge. I think this would be the case with all plugin-based approaches.

Hey @vonjones, you don't have to set the style directly, unfortunately there are color clashes with the backstage dark mode and mermaid's default theme, you can apply mermaid config to your Mermaid plugin through it's react component:

import { Mermaid } from 'backstage-plugin-techdocs-addon-mermaid';

(<TechDocsAddons>
  <Mermaid config={{ theme: 'forest', themeVariables: { lineColor: '#000000' } }} />
</TechDocsAddons>)

See Mermaid theme variables for what you can change.

I've found that if you like mermaids default theme, minimally you have to update to this:

themeVariables: { lineColor: '#666', arrowheadColor: '#666' }

This makes the line color slightly lighter than the default, but not the same color as backstage's dark theme background color.

[vonjones]

Thanks for the suggestion!

…

On Thu, Jan 5, 2023 at 1:10 PM Damon ***@***.***> wrote: We did not attempt this approach. Instead, we are using the backstage-plugin-techdocs-addon-mermaid plugin. It's working for the most part. The issues I'm seeing are: 1. Styling with the default dark mode theme is bad, since the black lines in the diagram don't show up on the dark background. We do see that it renders correctly if you change <div class="mermaid"> to <div class="mermaid" style="background-color: white"> in the browser, but have not made a code change to fix it yet. This seems like a 'bug" with the plugin. 2. It does not support the ability to use mkdocs serve to view your output locally. So for developers who do not use something like VScode with a preview function, it makes it hard for developers to see their diagram as they build, prior to merge. I think this would be the case with all plugin-based approaches. Hey @vonjones <https://github.com/vonjones>, you don't have to set the style directly, unfortunately there are color clashes with the backstage dark mode and mermaid's default theme, you can apply mermaid config to your Mermaid plugin through it's react component: import { Mermaid } from 'backstage-plugin-techdocs-addon-mermaid'; (<TechDocsAddons> <Mermaid config={{ theme: 'forest', themeVariables: { lineColor: '#000000' } }} /></TechDocsAddons>) See Mermaid theme variables <https://mermaid.js.org/config/theming.html#customizing-themes-with-themevariables> for what you can change. I've found that if you like mermaids default theme, minimally you have to update to this: themeVariables: { lineColor: '#666', arrowheadColor: '#666' } This makes the line color slightly lighter than the default, but not the same color as backstage's dark theme background color. — Reply to this email directly, view it on GitHub <#4123 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AD4YIQZ76TPCAH4FAVKIS3DWQ4MCHANCNFSM4WGMS3HQ> . You are receiving this because you were mentioned.Message ID: ***@***.***>

-- *Von Jones* PRINCIPAL Architect *E:* ***@***.*** *M:* 832-428-3846 *WP Engine, Inc.* 504 Lavaca Street, Suite 1000 Austin, Texas 78701 wpengine.com | twitter <https://twitter.com/wpengine> | careers <http://wpengine-careers.com/> | torquemag.io | velocitize.com

[johanneswuerbach]

If you think this change would generally make sense, please open an issue at https://github.com/johanneswuerbach/backstage-plugin-techdocs-addon-mermaid so the plugin provides a better out of the box experience 🙇‍♂️

[SteffanVerlaan]

Yes this worked for me and @KeesCBakker. Thanks guys!

[vonjones]

I was able to fix the Mermaid dark mode styling issue in my implementation by:

1. moving to the latest backstage-plugin-techdocs-addon-mermaid plugin (0.4.2)
2. Using some undocumented but present-in-source props. This helps to not have to find some greys that render between light and dark backgrounds, so I can have greater contrast.

in app.tsx:

import { Mermaid } from 'backstage-plugin-techdocs-addon-mermaid';
...
      <TechDocsAddons>
        <ReportIssue />
        <Mermaid
          darkConfig={{ theme: 'dark' }}
          lightConfig={{ theme: 'forest' }}
        />
      </TechDocsAddons>

[jvwrx]

Just a note on this old issue that we found another quick fix for getting the line color to match the theme was by specifying currentColor rather than a specific color, which allows it to inherit the color property of its parent (presumably black or white depending on the theme) and has very good support https://caniuse.com/?search=currentcolor

<Mermaid config={{ theme: 'forest', themeVariables: { lineColor: 'currentColor' } }} />

[ady642]

same bug for me, I see the mermaid as code

[johanneswuerbach]

Mermaid isn't rendered by default, you need a plugin (e.g. https://github.com/johanneswuerbach/backstage-plugin-techdocs-addon-mermaid) to render your diagrams.