From 765939e8b67bc90ad282805b9b19bc6e6464b558 Mon Sep 17 00:00:00 2001 From: Andre Wanlin Date: Thu, 8 Aug 2024 09:46:41 -0500 Subject: [PATCH] Updated mermaid tutorial to add markdown-inline-mermaid Signed-off-by: Andre Wanlin --- docs/features/techdocs/how-to-guides.md | 28 +++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/docs/features/techdocs/how-to-guides.md b/docs/features/techdocs/how-to-guides.md index 59198e919b..e47af8d1d7 100644 --- a/docs/features/techdocs/how-to-guides.md +++ b/docs/features/techdocs/how-to-guides.md @@ -580,6 +580,10 @@ Note: To refer external diagram files, we need to include the diagrams directory ## How to add Mermaid support in TechDocs +There are two options for adding Mermaid support in TechDocs: using [Kroki](https://kroki.io) or by using [markdown-inline-mermaid](https://github.com/johanneswuerbach/markdown-inline-mermaid). We currently use `markdown-inline-mermaid` for the [Mermaid example on the Demo site](https://demo.backstage.io/docs/default/component/backstage-demo/examples/mermaid/). + +### Using Kroki + To add `Mermaid` support in TechDocs, you can use [`kroki`](https://kroki.io) that creates diagrams from Textual descriptions. It is a single rendering gateway for all popular diagrams-as-a-code tools. It supports an enormous number @@ -678,6 +682,30 @@ Done! Now you have a support of the following diagrams along with mermaid: - `Vega-Lite` - `WaveDrom` +### Using `markdown-inline-mermaid` + +To use `markdown-inline-mermaid` to generate your Mermaid diagrams in TechDocs you'll need to do the following: + +1. In your Dockerfile you will need to make sure you install `markdown-inline-mermaid` like this: `RUN pip3 install mkdocs-techdocs-core markdown-inline-mermaid` +2. You will also need to install the `@mermaid-js/mermaid-cli`, to do that add this: `RUN yarn global add @mermaid-js/mermaid-cli` +3. Now in your `mkdocs.yml` file you will need to add the following section (this is at the root level like `plugins` which you should already have): + + ```yaml title="mkdocs.yml" + markdown_extensions: + - markdown_inline_mermaid + ``` + +4. With this in place you can now add Mermaid diagrams in your Markdown files like this: + + ````md + ```mermaid + sequenceDiagram + Alice->>John: Hello John, how are you? + John-->>Alice: Great! + Alice-)John: See you later! + ``` + ```` + ## How to implement a hybrid build strategy One limitation of the [Recommended deployment](./architecture.md#recommended-deployment) is that