From db75552b8bbc0f8124973a0b979e20b2da36cf24 Mon Sep 17 00:00:00 2001 From: Lakshika Parihar <31981299+lakshikaparihar@users.noreply.github.com> Date: Fri, 7 Jan 2022 21:08:38 +0530 Subject: [PATCH 1/4] Update how-to-guides.md Signed-off-by: lakshikaparihar --- docs/features/techdocs/how-to-guides.md | 85 +++++++++++++++++++++++++ 1 file changed, 85 insertions(+) diff --git a/docs/features/techdocs/how-to-guides.md b/docs/features/techdocs/how-to-guides.md index d9a8ffb93a..7a96135e2b 100644 --- a/docs/features/techdocs/how-to-guides.md +++ b/docs/features/techdocs/how-to-guides.md @@ -442,3 +442,88 @@ techdocs: This way, all iframes where the host of src attribute is in the `sanitizer.allowedIframeHosts` list will be displayed + +
+ +## How to add mermaid support in TechDocs + +To add `Mermaid support in Techdocs`, you can use [kroki](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 of diagram types. + +1. **Create and Publish docker image:** Create the `docker image` from the following dockerfile and publish it to `dockerHub`. + +```docker +FROM python:3.8-alpine + + +RUN apk update && apk --no-cache add gcc musl-dev openjdk11-jdk curl graphviz ttf-dejavu fontconfig + +RUN pip install --upgrade pip && pip install mkdocs-techdocs-core==0.2.1 + +RUN pip install mkdocs-kroki-plugin + +ENTRYPOINT [ "mkdocs" ] +``` + +Create a repository in your `DockerHub` and run the below command in the same folder where your `dockerfile` is present + +> docker build . -t dockerHub_Username/repositoryName:tagName + +Once the docker image is ready, push it to `DockerHub`. +
+ +2. **Update app-config.yaml:** So that when your app generates the techdoc, it will pull your docker image from `DockerHub`. + +```python +techdocs: + builder: 'local' # Alternatives - 'external' + generator: + runIn: 'docker' # Alternatives - 'local' + dockerImage: 'lakshika1064/backstage:techdocs' + pullImage: true + publisher: + type: 'local' # Alternatives - 'googleGcs' or 'awsS3'. Read documentation for using alternatives. + +``` + +3. **Add kroki plugin in Mkdocs.yml:** + +```yml +plugins: + - techdocs-core + - kroki +``` + +4. **Add mermaid code into techdoc:** + +```md +```kroki-mermaid +sequenceDiagram +GitLab->>Kroki: Request rendering +Kroki->>Mermaid: Request rendering +Mermaid-->>Kroki: Image +Kroki-->>GitLab: Image +``` + +Done! Now you have a support of the following diagrams along with mermaid: + +- PlantUML +- BlockDiag +- BPMN +- ByteField +- SeqDiag +- ActDiag +- NwDiag +- PacketDiag +- RackDiag +- C4 with PlantUML +- Ditaa +- Erd +- Excalidraw +- GraphViz +- Nomnoml +- Pikchr +- Svgbob +- UMlet +- Vega +- Vega-Lite +- WaveDrom From 0988d56b69b13e842fd7d9be618459167987c7b4 Mon Sep 17 00:00:00 2001 From: lakshikaparihar Date: Tue, 11 Jan 2022 12:36:39 +0530 Subject: [PATCH 2/4] formatted md file Signed-off-by: lakshikaparihar --- docs/features/techdocs/how-to-guides.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/features/techdocs/how-to-guides.md b/docs/features/techdocs/how-to-guides.md index 7a96135e2b..9eeb1758a1 100644 --- a/docs/features/techdocs/how-to-guides.md +++ b/docs/features/techdocs/how-to-guides.md @@ -478,7 +478,7 @@ techdocs: builder: 'local' # Alternatives - 'external' generator: runIn: 'docker' # Alternatives - 'local' - dockerImage: 'lakshika1064/backstage:techdocs' + dockerImage: dockerHub_Username/repositoryName:tagName pullImage: true publisher: type: 'local' # Alternatives - 'googleGcs' or 'awsS3'. Read documentation for using alternatives. @@ -493,9 +493,9 @@ plugins: - kroki ``` -4. **Add mermaid code into techdoc:** +4. **Add mermaid code into techdocs:** -```md +````md ```kroki-mermaid sequenceDiagram GitLab->>Kroki: Request rendering @@ -503,6 +503,7 @@ Kroki->>Mermaid: Request rendering Mermaid-->>Kroki: Image Kroki-->>GitLab: Image ``` +```` Done! Now you have a support of the following diagrams along with mermaid: From ab2ae2a28cf23fd4915735307924caaf3c32bc08 Mon Sep 17 00:00:00 2001 From: lakshikaparihar Date: Tue, 11 Jan 2022 13:26:41 +0530 Subject: [PATCH 3/4] formatted code with prettier Signed-off-by: lakshikaparihar --- docs/features/techdocs/how-to-guides.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/features/techdocs/how-to-guides.md b/docs/features/techdocs/how-to-guides.md index 9eeb1758a1..ff85a9b2a8 100644 --- a/docs/features/techdocs/how-to-guides.md +++ b/docs/features/techdocs/how-to-guides.md @@ -132,7 +132,7 @@ maintain such a component in a new directory at `packages/app/src/components/techdocs`, and import and use it in `App.tsx`: ```tsx -import { CustomTechDocsHome } from './components/techdocs/CustomTechDocsHome'; +import { CustomTechDocsHome } from "./components/techdocs/CustomTechDocsHome"; // ... const AppRoutes = () => { @@ -407,9 +407,9 @@ plugins: The `docs/index.md` can for example have the following content: ```md -# ${{ values.component_id }} +# \${{ values.component_id }} -${{ values.description }} +\${{ values.description }} ## Getting started From 9565610509c261fea7bedb668fe96f1f4785d5f8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= Date: Wed, 19 Jan 2022 15:20:06 +0100 Subject: [PATCH 4/4] prettier MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fredrik Adelöw --- docs/features/techdocs/how-to-guides.md | 81 +++++++++++++------------ 1 file changed, 42 insertions(+), 39 deletions(-) diff --git a/docs/features/techdocs/how-to-guides.md b/docs/features/techdocs/how-to-guides.md index ff85a9b2a8..1885c1a961 100644 --- a/docs/features/techdocs/how-to-guides.md +++ b/docs/features/techdocs/how-to-guides.md @@ -132,7 +132,7 @@ maintain such a component in a new directory at `packages/app/src/components/techdocs`, and import and use it in `App.tsx`: ```tsx -import { CustomTechDocsHome } from "./components/techdocs/CustomTechDocsHome"; +import { CustomTechDocsHome } from './components/techdocs/CustomTechDocsHome'; // ... const AppRoutes = () => { @@ -406,10 +406,10 @@ plugins: The `docs/index.md` can for example have the following content: -```md -# \${{ values.component_id }} +``` +# ${{ values.component_id }} -\${{ values.description }} +${{ values.description }} ## Getting started @@ -441,20 +441,21 @@ techdocs: ``` This way, all iframes where the host of src attribute is in the -`sanitizer.allowedIframeHosts` list will be displayed +`sanitizer.allowedIframeHosts` list will be displayed. -
+## How to add Mermaid support in TechDocs -## How to add mermaid support in TechDocs +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 +of diagram types. -To add `Mermaid support in Techdocs`, you can use [kroki](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 of diagram types. - -1. **Create and Publish docker image:** Create the `docker image` from the following dockerfile and publish it to `dockerHub`. +1. **Create and Publish docker image:** Create the docker image from the + following Dockerfile and publish it to DockerHub. ```docker FROM python:3.8-alpine - RUN apk update && apk --no-cache add gcc musl-dev openjdk11-jdk curl graphviz ttf-dejavu fontconfig RUN pip install --upgrade pip && pip install mkdocs-techdocs-core==0.2.1 @@ -464,14 +465,17 @@ RUN pip install mkdocs-kroki-plugin ENTRYPOINT [ "mkdocs" ] ``` -Create a repository in your `DockerHub` and run the below command in the same folder where your `dockerfile` is present +Create a repository in your DockerHub and run the below command in the same +folder where your Dockerfile is present: -> docker build . -t dockerHub_Username/repositoryName:tagName +```shell +docker build . -t dockerHub_Username/repositoryName:tagName +``` -Once the docker image is ready, push it to `DockerHub`. -
+Once the docker image is ready, push it to DockerHub. -2. **Update app-config.yaml:** So that when your app generates the techdoc, it will pull your docker image from `DockerHub`. +2. **Update app-config.yaml:** So that when your app generates techdocs, it will + pull your docker image from DockerHub. ```python techdocs: @@ -482,10 +486,9 @@ techdocs: pullImage: true publisher: type: 'local' # Alternatives - 'googleGcs' or 'awsS3'. Read documentation for using alternatives. - ``` -3. **Add kroki plugin in Mkdocs.yml:** +3. **Add the `kroki` plugin in mkdocs.yml:** ```yml plugins: @@ -507,24 +510,24 @@ Kroki-->>GitLab: Image Done! Now you have a support of the following diagrams along with mermaid: -- PlantUML -- BlockDiag -- BPMN -- ByteField -- SeqDiag -- ActDiag -- NwDiag -- PacketDiag -- RackDiag -- C4 with PlantUML -- Ditaa -- Erd -- Excalidraw -- GraphViz -- Nomnoml -- Pikchr -- Svgbob -- UMlet -- Vega -- Vega-Lite -- WaveDrom +- `PlantUML` +- `BlockDiag` +- `BPMN` +- `ByteField` +- `SeqDiag` +- `ActDiag` +- `NwDiag` +- `PacketDiag` +- `RackDiag` +- `C4 with PlantUML` +- `Ditaa` +- `Erd` +- `Excalidraw` +- `GraphViz` +- `Nomnoml` +- `Pikchr` +- `Svgbob` +- `UMlet` +- `Vega` +- `Vega-Lite` +- `WaveDrom`