From b5c2256cc0bd056a037415391e4696bb06caadd4 Mon Sep 17 00:00:00 2001 From: Adam Harvey Date: Thu, 4 May 2023 10:52:42 -0400 Subject: [PATCH 1/3] chore: Improve docs wording Signed-off-by: Adam Harvey --- docs/features/techdocs/how-to-guides.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/features/techdocs/how-to-guides.md b/docs/features/techdocs/how-to-guides.md index ceccbe1468..3789d8582d 100644 --- a/docs/features/techdocs/how-to-guides.md +++ b/docs/features/techdocs/how-to-guides.md @@ -509,8 +509,8 @@ Done! You now have support for TechDocs in your own software template! ## how to enable iframes in TechDocs -Techdocs uses the [DOMPurify](https://github.com/cure53/DOMPurify) to sanitizes -HTML and prevents XSS attacks +TechDocs uses the [DOMPurify](https://github.com/cure53/DOMPurify) library to +sanitize HTML and prevent XSS attacks. It's possible to allow some iframes based on a list of allowed hosts. To do this, add the allowed hosts in the `techdocs.sanitizer.allowedIframeHosts` @@ -530,7 +530,7 @@ This way, all iframes where the host of src attribute is in the ## How to add Mermaid support in TechDocs -To add `Mermaid` support in Techdocs, you can use [`kroki`](https://kroki.io) +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. @@ -559,7 +559,7 @@ 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 techdocs, it will +2. **Update app-config.yaml:** So that when your app generates TechDocs, it will pull your docker image from DockerHub. ```python From f8ac46f62739df9f656d74902cc3f6f606a541f5 Mon Sep 17 00:00:00 2001 From: Adam Harvey Date: Thu, 4 May 2023 13:45:51 -0400 Subject: [PATCH 2/3] chore: Additional cleanup and formatting Signed-off-by: Adam Harvey --- docs/features/techdocs/how-to-guides.md | 27 +++++++++---------------- 1 file changed, 10 insertions(+), 17 deletions(-) diff --git a/docs/features/techdocs/how-to-guides.md b/docs/features/techdocs/how-to-guides.md index 3789d8582d..3d86de53f2 100644 --- a/docs/features/techdocs/how-to-guides.md +++ b/docs/features/techdocs/how-to-guides.md @@ -335,7 +335,6 @@ bucket matches this lower-case entity triplet expectation. able to read/copy/rename/move/delete files. The exact instructions vary by storage provider, but check the [using cloud storage][using-cloud-storage] page for details. - 2. **Run a non-destructive migration of files**: Ensure you have the latest version of `techdocs-cli` installed. Then run the following command, using the details relevant for your provider / configuration. This will copy all @@ -349,12 +348,10 @@ techdocs-cli migrate --publisher-type --stora 3. **Deploy the updated versions of the TechDocs plugins**: Once the migration above has been run, you can deploy the beta versions of the TechDocs backend and frontend plugins to your Backstage instance. - 4. **Verify that your TechDocs sites are still loading/accessible**: Try accessing a TechDocs site using different entity-triplet case variants, e.g. `/docs/namespace/KIND/name` or `/docs/namespace/kind/name`. Your TechDocs site should load regardless of the URL path casing you use. - 5. **Clean up the old objects from storage**: Once you've verified that your TechDocs site is accessible, you can clean up your storage bucket by re-running the `migrate` command on the TechDocs CLI, but with an additional @@ -491,7 +488,7 @@ plugins: The `docs/index.md` can for example have the following content: -``` +```markdown # ${{ values.component_id }} ${{ values.description }} @@ -535,15 +532,15 @@ 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 +FROM python:3.10-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==1.1.7 +RUN pip install --upgrade pip && pip install mkdocs-techdocs-core==1.2.0 RUN pip install mkdocs-kroki-plugin @@ -551,16 +548,14 @@ ENTRYPOINT [ "mkdocs" ] ``` Create a repository in your DockerHub and run the below command in the same -folder where your Dockerfile is present: +folder where your `Dockerfile` is present: ```shell 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 TechDocs, it will - pull your docker image from DockerHub. +Once the docker image is ready, push it to DockerHub. 2. **Update app-config.yaml:** So that when your app generates TechDocs, it will +pull your docker image from DockerHub. ```python techdocs: @@ -573,7 +568,7 @@ techdocs: type: 'local' # Alternatives - 'googleGcs' or 'awsS3'. Read documentation for using alternatives. ``` -3. **Add the `kroki` plugin in mkdocs.yml:** +3. **Add the `kroki` plugin in `mkdocs.yml`:** ```yml plugins: @@ -586,9 +581,7 @@ plugins: > you have sensitive information in your organization's diagrams, you should set > up a [server of your own](https://docs.kroki.io/kroki/setup/install/) and use it > instead. Check out [mkdocs-kroki-plugin config](https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin#config) -> for more plugin configuration details. - -4. **Add mermaid code into techdocs:** +> for more plugin configuration details. 4. **Add mermaid code into TechDocs:** ````md ```kroki-mermaid From 9fc9d2a73684dfb20b4bcec18b49be7bbb1ad42b Mon Sep 17 00:00:00 2001 From: Adam Harvey Date: Thu, 4 May 2023 13:48:37 -0400 Subject: [PATCH 3/3] chore: More formatting Signed-off-by: Adam Harvey --- docs/features/techdocs/how-to-guides.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/features/techdocs/how-to-guides.md b/docs/features/techdocs/how-to-guides.md index 3d86de53f2..a45112bcfe 100644 --- a/docs/features/techdocs/how-to-guides.md +++ b/docs/features/techdocs/how-to-guides.md @@ -335,6 +335,7 @@ bucket matches this lower-case entity triplet expectation. able to read/copy/rename/move/delete files. The exact instructions vary by storage provider, but check the [using cloud storage][using-cloud-storage] page for details. + 2. **Run a non-destructive migration of files**: Ensure you have the latest version of `techdocs-cli` installed. Then run the following command, using the details relevant for your provider / configuration. This will copy all @@ -348,10 +349,12 @@ techdocs-cli migrate --publisher-type --stora 3. **Deploy the updated versions of the TechDocs plugins**: Once the migration above has been run, you can deploy the beta versions of the TechDocs backend and frontend plugins to your Backstage instance. + 4. **Verify that your TechDocs sites are still loading/accessible**: Try accessing a TechDocs site using different entity-triplet case variants, e.g. `/docs/namespace/KIND/name` or `/docs/namespace/kind/name`. Your TechDocs site should load regardless of the URL path casing you use. + 5. **Clean up the old objects from storage**: Once you've verified that your TechDocs site is accessible, you can clean up your storage bucket by re-running the `migrate` command on the TechDocs CLI, but with an additional @@ -554,8 +557,10 @@ 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 TechDocs, it will -pull your docker image from DockerHub. +Once the docker image is ready, push it to DockerHub. + +2. **Update app-config.yaml:** So that when your app generates TechDocs, it will + pull your docker image from DockerHub. ```python techdocs: @@ -581,7 +586,9 @@ plugins: > you have sensitive information in your organization's diagrams, you should set > up a [server of your own](https://docs.kroki.io/kroki/setup/install/) and use it > instead. Check out [mkdocs-kroki-plugin config](https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin#config) -> for more plugin configuration details. 4. **Add mermaid code into TechDocs:** +> for more plugin configuration details. + +4. **Add mermaid code into TechDocs:** ````md ```kroki-mermaid