Merge pull request #210 from awanlin/topic/techdocs-example

Added TechDocs examples and related changes

.github/workflows/techdocs.yml

@@ -29,7 +29,7 @@ jobs:
         with:
           node-version: 18.x
           registry-url: https://registry.npmjs.org/ # Needed for auth
-      
+
       - name: Setup Python 3.9
         uses: actions/setup-python@v4
         with:
@@ -41,13 +41,24 @@ jobs:
       - name: Install MkDocs and MkDocs Plugins
         run: python -m pip install mkdocs-techdocs-core==1.*
 
+      - name: Clean Up Readmes
+        run: |
+          for i in README*.md; do
+            sed -i 's|docs/assets|assets|g' $i
+            sed -i 's|README.md|index.md|g' $i
+          done
+
+      - name: Copy Translated Readmes
+        run: |
+          mv README-*.md docs
+
       - name: Generate TechDocs
         run: techdocs-cli generate --no-docker --legacyCopyReadmeMdToIndexMd --verbose
 
       - name: Login to Google Cloud Services
         uses: 'google-github-actions/auth@v2'
         with:
           credentials_json: ${{ secrets.TECHDOCS_GCS_CREDENTIALS_JSON }}
-      
+
       - name: Publish TechDocs
         run: techdocs-cli publish --publisher-type googleGcs --storage-name ${{ secrets.TECHDOCS_GCS_BUCKET }} --entity default/component/backstage

Dockerfile

@@ -61,8 +61,21 @@ ENV PYTHON /usr/bin/python3
 RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
     --mount=type=cache,target=/var/lib/apt,sharing=locked \
     apt-get update && \
-    apt-get install -y --no-install-recommends libsqlite3-dev python3 build-essential && \
-    rm -rf /var/lib/apt/lists/*
+    apt-get install -y --no-install-recommends libsqlite3-dev \
+    python3 python3-pip python3-venv \
+    curl default-jre graphviz fonts-dejavu fontconfig && \
+    rm -rf /var/lib/apt/lists/* && \
+    yarn config set python /usr/bin/python3
+
+ENV VIRTUAL_ENV=/opt/venv
+RUN python3 -m venv $VIRTUAL_ENV
+ENV PATH="$VIRTUAL_ENV/bin:$PATH"
+
+RUN pip3 install mkdocs-techdocs-core mkdocs-kroki-plugin
+
+RUN curl -o plantuml.jar -L https://github.com/plantuml/plantuml/releases/download/v1.2023.10/plantuml-1.2023.10.jar && echo "527d28af080ae91a455e7023e1a726c7714dc98e plantuml.jar" | sha1sum -c - && mv plantuml.jar /opt/plantuml.jar
+RUN echo '#!/bin/sh\n\njava -jar '/opt/plantuml.jar' ${@}' >> /usr/local/bin/plantuml
+RUN chmod 755 /usr/local/bin/plantuml
 
 # From here on we use the least-privileged `node` user to run the backend.
 USER node
@@ -86,8 +99,9 @@ COPY --from=build --chown=node:node /app/packages/backend/dist/bundle/ ./
 # Copy any other files that we need at runtime
 COPY --chown=node:node app-config.yaml app-config.*.yaml ./
 
-
-ENV PORT 7000
+# Heroku will assign the port dynamically; the default value here will be overridden by what Heroku passes in
+# For local development the default will be used
+ENV PORT 7007
 # This switches many Node.js dependencies to production mode.
 ENV NODE_ENV production
 # Sets the max memory size of V8's old memory section

app-config.heroku.yaml

@@ -4,7 +4,8 @@ app:
 backend:
   baseUrl: https://demo.backstage.io
   listen:
-    port: ${PORT}
+    # Heroku will assign the port dynamically so we want to just pass that in as is
+    port: ${PORT} 
   auth:
     keys:
       - secret: ${BACKEND_AUTH_KEY}
@@ -20,8 +21,9 @@ auth:
         clientSecret: ${GITHUB_PRODUCTION_CLIENT_SECRET}
 
 techdocs:
-  requestUrl: https://demo.backstage.io/api/techdocs
-  storageUrl: https://demo.backstage.io/api/techdocs/static/docs
+  sanitizer:
+    allowedIframeHosts:
+      - www.youtube.com
   builder: 'external'
   publisher:
     type: 'googleGcs'

app-config.yaml

@@ -24,7 +24,16 @@ backend:
     port: 7007
   csp:
     connect-src: ["'self'", 'http:', 'https:']
-    img-src: ["'self'", 'data:', 'https://backstage.io', 'https://img.shields.io', 'https://api.dicebear.com/']
+    img-src:
+      [
+        "'self'",
+        'data:',
+        'https://backstage.io',
+        'https://img.shields.io/',
+        'https://api.dicebear.com/',
+        'https://kroki.io/',
+      ]
+    frame-src: ['https://www.youtube.com']
   cors:
     origin: http://localhost:3000
     methods: [GET, POST, PUT, DELETE]
@@ -80,9 +89,9 @@ catalog:
     - type: url
       target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/all-resources.yaml
 
-    # The backstage demo deployment (this)
-    - type: url
-      target: https://github.com/backstage/demo/blob/master/catalog-info.yaml
+    # # The backstage demo deployment (this)
+    # - type: url
+    #   target: https://github.com/backstage/demo/blob/master/catalog-info.yaml
 
     # The backstage library repository
     - type: url
@@ -107,9 +116,10 @@ costInsights:
     MSC:
       name: Monthly Subscribers
 
-# app-config.heroku.yaml replaces these values
-# These configs here are required for config validation in CI to pass
 techdocs:
+  sanitizer:
+    allowedIframeHosts:
+      - www.youtube.com
   builder: 'external'
   generator:
     runIn: 'local'

catalog-info.yaml

@@ -5,6 +5,8 @@ metadata:
   description: An example deployment of a Backstage application.
   annotations:
     github.com/project-slug: backstage/demo
+    backstage.io/techdocs-ref: dir:.
+    demo.backstage.io/techdocs-builder: local
 spec:
   type: website
   owner: backstage/maintainers

docs/examples/iframe.md

@@ -0,0 +1,25 @@
+# iframe
+
+## Overview
+
+This page shows how you can use an iframe in TechDocs.
+
+## Explanation
+
+To be able to use iframes with TechDocs you'll need to follow this guide: [How to enable iframes in TechDocs](https://backstage.io/docs/features/techdocs/how-to-guides#how-to-enable-iframes-in-techdocs)
+
+## Example
+
+Here is an example:
+
+<iframe width="672" height="378" src="https://www.youtube.com/embed/85TQEpNCaU0" title="YouTube video player" frameborder="0" allow="picture-in-picture" allowfullscreen></iframe>
+
+## Markdown
+
+Here is the Markdown:
+
+```markdown
+<iframe width="672" height="378" frameborder="0"
+src="https://www.youtube.com/embed/85TQEpNCaU0" title="YouTube video player" 
+allow="picture-in-picture" allowfullscreen></iframe>
+```

docs/examples/lists.md

@@ -0,0 +1,37 @@
+# Lists
+
+## Overview
+
+This page shows how you can use lists in TechDocs.
+
+## Explanation
+
+The [`techdocs-core`](https://github.com/backstage/mkdocs-techdocs-core) MkDocs plugin includes the [`mdx_truly_sane_lists`](https://github.com/radude/mdx_truly_sane_lists) plugin which has a default of 2, this means that each nested list needs to be 2 spaces under its parent.
+
+## Example
+
+Here is an example:
+
+1. A list item
+2. Another list item
+  1. The first sub item
+  2. Another sub item
+    1. Oh wait, we have a deeply nested item here
+    2. Why not another, you might need it!
+  3. A third and final sub item
+3. The last item in this list
+
+## Markdown
+
+Here is the Markdown:
+
+```markdown
+1. A list item
+2. Another list item
+  1. The first sub item
+  2. Another sub item
+    1. Oh wait, we have a deeply nested item here
+    2. Why not another, you might need it!
+  3. A third and final sub item
+3. The last item in this list
+```

docs/examples/mermaid.md

@@ -0,0 +1,36 @@
+# Mermaid
+
+## Overview
+
+This page shows how you can use [Mermaid](https://mermaid.js.org/intro/) in TechDocs.
+
+## Explanation
+
+To be able to use Mermaid diagrams with TechDocs you'll need to follow this guide: [How to add Mermaid support in TechDocs](https://backstage.io/docs/features/techdocs/how-to-guides#how-to-add-mermaid-support-in-techdocs).
+
+## Example
+
+Here is an example:
+
+```kroki-mermaid
+sequenceDiagram
+    Alice->>John: Hello John, how are you?
+    John-->>Alice: Great!
+    Alice-)John: See you later!
+```
+
+>Note: For this example we are using [Kroki.io](https://kroki.io/), but you may which to run your own server to protect TechDocs with sensitive content. More details on this topic are in the previously linked guide.
+
+## Markdown
+
+Here is the Markdown:
+
+```markdown
+kroki-mermaid
+sequenceDiagram
+    Alice->>John: Hello John, how are you?
+    John-->>Alice: Great!
+    Alice-)John: See you later!
+```
+
+>Note: in order to prevent Mermaid from rendering the diagram above the backticks (\`) have been removed. You'll want to add 3 backticks on line 1 before `kroki-mermaid` and then another 3 backticks on a new line below line 5.

docs/examples/plantuml.md

@@ -0,0 +1,38 @@
+# PlantUML
+
+## Overview
+
+This page shows how you can use [PlantUML](https://plantuml.com/) in TechDocs.
+
+## Explanation
+
+The [`techdocs-core`](https://github.com/backstage/mkdocs-techdocs-core) MkDocs plugin includes the [`plantuml-markdown`](https://github.com/mikitex70/plantuml-markdown) plugin which allows you to add PlantUML diagrams in your Markdown easily.
+
+## Example
+
+Here is an example:
+
+```plantuml
+@startuml
+title Login Sequence
+    ComponentA->ComponentB: Login Request
+    note right of ComponentB: ComponentB logs message
+    ComponentB->ComponentA: Login Response
+@enduml
+```
+
+## Markdown
+
+Here is the Markdown:
+
+```markdown
+plantuml
+@startuml
+title Login Sequence
+    ComponentA->ComponentB: Login Request
+    note right of ComponentB: ComponentB logs message
+    ComponentB->ComponentA: Login Response
+@enduml
+```
+
+>Note: in order to prevent PlantUML from rendering the diagram above the backticks (\`) have been removed. You'll want to add 3 backticks on line 1 before `plantuml` and then another 3 backticks on a new line below line 7.

docs/index.md

@@ -0,0 +1,14 @@
+# TechDocs
+
+## Overview
+
+This set of documentation is intended to show simple working examples of TechDocs.
+
+## Examples
+
+Current examples:
+
+- [iframe](./examples/iframe.md): this shows how you can use an iframe in your TechDocs
+- [Lists](./examples/lists.md): this showcases how to setup your lists in TechDocs
+- [Mermaid](./examples/mermaid.md): this showcases how to use Mermaid diagrams in your TechDocs
+- [PlantUML](./examples/plantuml.md): this showcases how to use PlantUML diagrams in your TechDocs

mkdocs.yml

@@ -0,0 +1,5 @@
+site_name: 'Backstage Demo'
+
+plugins:
+  - techdocs-core
+  - kroki

packages/backend/package.json

@@ -18,6 +18,7 @@
   "dependencies": {
     "@backstage/backend-common": "^0.20.1-next.2",
     "@backstage/backend-defaults": "^0.2.9-next.2",
+    "@backstage/backend-plugin-api": "^0.6.9-next.2",
     "@backstage/backend-tasks": "^0.5.14-next.2",
     "@backstage/config": "^1.1.1",
     "@backstage/plugin-app-backend": "^0.3.57-next.2",
@@ -34,6 +35,7 @@
     "@backstage/plugin-search-backend-module-catalog": "^0.1.13-next.2",
     "@backstage/plugin-search-backend-module-explore": "^0.1.13-next.2",
     "@backstage/plugin-techdocs-backend": "^1.9.2-next.2",
+    "@backstage/plugin-techdocs-node": "^1.11.1-next.2",
     "@backstage/plugin-todo-backend": "^0.3.7-next.2",
     "@frontside/backstage-plugin-graphql-backend": "^0.1.2",
     "@frontside/backstage-plugin-graphql-backend-module-catalog": "^0.1.2",

packages/backend/src/extensions/docsBuildStrategy.ts

@@ -0,0 +1,25 @@
+import { createBackendModule } from '@backstage/backend-plugin-api';
+import {
+  DocsBuildStrategy,
+  techdocsBuildsExtensionPoint,
+} from '@backstage/plugin-techdocs-node';
+
+export default createBackendModule({
+  pluginId: 'techdocs',
+  moduleId: 'customBuildStrategy',
+  register(env) {
+    env.registerInit({
+      deps: {
+        techdocs: techdocsBuildsExtensionPoint,
+      },
+      async init({ techdocs }) {
+        const docsBuildStrategy: DocsBuildStrategy = {
+          shouldBuild: async params =>
+            params.entity.metadata?.annotations?.['demo.backstage.io/techdocs-builder'] === 'local',
+        };
+
+        techdocs.setBuildStrategy(docsBuildStrategy);
+      },
+    });
+  },
+});

packages/backend/src/index.ts

@@ -19,8 +19,12 @@ backend.add(import('@backstage/plugin-proxy-backend/alpha'));
 backend.add(import('@backstage/plugin-search-backend/alpha'));
 backend.add(import('@backstage/plugin-search-backend-module-catalog/alpha'));
 backend.add(import('@backstage/plugin-search-backend-module-explore/alpha'));
+// TODO:(awanlin) enable when issue causing crashes is resolved
 // backend.add(import('@backstage/plugin-search-backend-module-techdocs/alpha'));
+
 backend.add(import('@backstage/plugin-techdocs-backend/alpha'));
+backend.add(import('./extensions/docsBuildStrategy'));
+
 backend.add(import('@backstage/plugin-todo-backend'));
 
 backend.start();

yarn.lock

@@ -12825,6 +12825,7 @@ __metadata:
   dependencies:
     "@backstage/backend-common": ^0.20.1-next.2
     "@backstage/backend-defaults": ^0.2.9-next.2
+    "@backstage/backend-plugin-api": ^0.6.9-next.2
     "@backstage/backend-tasks": ^0.5.14-next.2
     "@backstage/cli": ^0.25.1-next.1
     "@backstage/config": ^1.1.1
@@ -12842,6 +12843,7 @@ __metadata:
     "@backstage/plugin-search-backend-module-catalog": ^0.1.13-next.2
     "@backstage/plugin-search-backend-module-explore": ^0.1.13-next.2
     "@backstage/plugin-techdocs-backend": ^1.9.2-next.2
+    "@backstage/plugin-techdocs-node": ^1.11.1-next.2
     "@backstage/plugin-todo-backend": ^0.3.7-next.2
     "@frontside/backstage-plugin-graphql-backend": ^0.1.2
     "@frontside/backstage-plugin-graphql-backend-module-catalog": ^0.1.2