backstage-plugin-techdocs-addon-mermaid
TypeScript icon, indicating that this package has built-in type declarations

0.11.0 • Public • Published

backstage-plugin-techdocs-addon-mermaid

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+

Getting started

  1. Follow the official documentation for TechDocs Addons to enable addons for techdocs.

  2. 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
  3. 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
    
  4. 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>

Use Mermaid in your TechDocs

# Mermaid section

Here is a mermaid graph!

```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
```

Auto-Detection vs. Manual Detection

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

Package Sidebar

Install

npm i backstage-plugin-techdocs-addon-mermaid

Weekly Downloads

3,131

Version

0.11.0

License

MIT

Unpacked Size

22.1 kB

Total Files

10

Last publish

Collaborators

  • johanneswuerbach