diff --git a/.github/workflows/techdocs.yml b/.github/workflows/techdocs.yml index 1d209758b..a00212548 100644 --- a/.github/workflows/techdocs.yml +++ b/.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,6 +41,17 @@ 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 @@ -48,6 +59,6 @@ jobs: 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 diff --git a/Dockerfile b/Dockerfile index 1af9c465e..9c7efbbfa 100644 --- a/Dockerfile +++ b/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 diff --git a/app-config.heroku.yaml b/app-config.heroku.yaml index 460fd17c1..afa92faab 100644 --- a/app-config.heroku.yaml +++ b/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' diff --git a/app-config.yaml b/app-config.yaml index 69c93b5cb..04411a926 100644 --- a/app-config.yaml +++ b/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' diff --git a/catalog-info.yaml b/catalog-info.yaml index fdecdaad7..1016e6b27 100644 --- a/catalog-info.yaml +++ b/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 diff --git a/docs/examples/iframe.md b/docs/examples/iframe.md new file mode 100644 index 000000000..a354afcb3 --- /dev/null +++ b/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: + + + +## Markdown + +Here is the Markdown: + +```markdown + +``` diff --git a/docs/examples/lists.md b/docs/examples/lists.md new file mode 100644 index 000000000..6dc0778c4 --- /dev/null +++ b/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 +``` diff --git a/docs/examples/mermaid.md b/docs/examples/mermaid.md new file mode 100644 index 000000000..41647f638 --- /dev/null +++ b/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. diff --git a/docs/examples/plantuml.md b/docs/examples/plantuml.md new file mode 100644 index 000000000..b489c2b75 --- /dev/null +++ b/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. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..6ab12961d --- /dev/null +++ b/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 diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 000000000..e54a5006d --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,5 @@ +site_name: 'Backstage Demo' + +plugins: + - techdocs-core + - kroki diff --git a/packages/backend/package.json b/packages/backend/package.json index 781be8bd9..d6079e25a 100644 --- a/packages/backend/package.json +++ b/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", diff --git a/packages/backend/src/extensions/docsBuildStrategy.ts b/packages/backend/src/extensions/docsBuildStrategy.ts new file mode 100644 index 000000000..0a929f4e4 --- /dev/null +++ b/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); + }, + }); + }, +}); diff --git a/packages/backend/src/index.ts b/packages/backend/src/index.ts index 5c422ddc8..02476031a 100644 --- a/packages/backend/src/index.ts +++ b/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(); diff --git a/yarn.lock b/yarn.lock index 05f1d5f32..d34ff25e1 100644 --- a/yarn.lock +++ b/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