The backstage-plugin-techdocs-addon-mermaid
allows rendering of Mermaid diagrams
within Backstage TechDocs
This plugin is a Backstage TechDocs Addon, which requires Backstage v1.2+
Follow the official documentation for TechDocs Addons to enable addons for techdocs.
For your backstage instance, make sure you have installed mkdocs-techdocs-core
>= 1.0.2. Older versions will not render mermaid correctly!
pip3 install mkdocs-techdocs-core==1.0.2
Install this plugin in your backstage app. Run the following command from the root of your backstage installation:
yarn add --cwd packages/app backstage-plugin-techdocs-addon-mermaid
Enable the addon within techdocs viewer's within App.tsx
and EntityPage.tsx
// packages/app/src/App.tsx
// packages/app/src/components/catalog/EntityPage.tsx
import { Mermaid } from 'backstage-plugin-techdocs-addon-mermaid';
// ...
{techDocsPage}
<TechDocsAddons>
{/*...*/}
<Mermaid config={{ theme: 'forest', themeVariables: { lineColor: '#000000' } }} />
</TechDocsAddons>
# Mermaid section
Here is a mermaid graph!
```mermaid
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
```
By default, this plugin will autodetect diagrams based on the starting token of the code block. In some cases, however, this auto-detection is not sufficient, for example, because of an unrecognized
diagram type or the use of front matter. In these cases, you can force the use of mermaid on blocks by adding configuration like this to your mkdocs.yaml
file:
markdown_extensions:
pymdownx.extra:
pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
This plugin can be developed in the context of an existing Backstage deployment or a new local deployment.
plugins/backstage-plugin-techdocs-addon-mermaid folder
and run yarn link
.yarn link "backstage-plugin-techdocs-addon-mermaid
.yarn install
in the Backstage root.app.tsx
.After making changes to the plugin and having unit tests pass, to do manual end-to-end testing, follow the instructions below.
You can use the TechDocs CLI to test against a local docs folder. You will need to customize the preview app bundle for that to work as the addon is not included in the standard bundle. Review the TechDoc's documentation for further instructions.
Register a component via URL like any other Backstage component and view that component's TechDocs. For example, to use the SampleDocs component in this repo:
app-config.local.yaml
.yarn dev
in the root of your Backstage codebase.http://localhost:3000/catalog-import
https://github.com/johanneswuerbach/backstage-plugin-techdocs-addon-mermaid/blob/main/sampledocs/catalog-info.yaml