diff --git a/.github/workflows/deploy_microsite.yml b/.github/workflows/deploy_microsite.yml index ac02794268..c5d8cc26c2 100644 --- a/.github/workflows/deploy_microsite.yml +++ b/.github/workflows/deploy_microsite.yml @@ -8,14 +8,148 @@ permissions: contents: read jobs: - deploy-microsite-and-storybook: - permissions: - contents: write # for JamesIves/github-pages-deploy-action to push changes in repo + stable: runs-on: ubuntu-latest + concurrency: + group: stable-reference-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true env: CI: true NODE_OPTIONS: --max-old-space-size=8192 + + outputs: + release: ${{ steps.find-release.outputs.result }} + + steps: + - name: Harden Runner + uses: step-security/harden-runner@5c7944e73c4c2a096b17a9cb74d65b6c2bbafbde # v2.9.1 + with: + egress-policy: audit + + - name: find latest release + uses: actions/github-script@v7 + id: find-release + with: + script: | + const { data } = await github.rest.repos.listTags({ + owner: context.repo.owner, + repo: context.repo.repo, + per_page: 100, + }) + + const [{tag}] = data + .map(i => i.name) + .filter(tag => tag.match(/^v\d+\.\d+\.\d+$/)) + .map(tag => ({ + tag, + val: tag + .slice(1) + .split('.') + .reduce((val, part) => Number(val) * 1000 + Number(part)) + })) + .sort((a, b) => b.val - a.val) + + return tag + result-encoding: string + + - name: checkout latest release + uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7 + with: + ref: refs/tags/${{ steps.find-release.outputs.result }} + + - name: use node.js 18.x + uses: actions/setup-node@1e60f620b9541d16bece96c5465dc8ee9832be0b # v4.0.3 + with: + node-version: 18.x + registry-url: https://registry.npmjs.org/ # Needed for auth + + - name: yarn install + uses: backstage/actions/yarn-install@3c138326f7fcbf253b88170c1f29bae8e975d47c # v0.6.14 + with: + cache-prefix: ${{ runner.os }}-v18.x + + - name: build API reference + run: yarn build:api-docs + + - name: upload API reference + uses: actions/upload-artifact@v4 + with: + name: stable-reference + path: docs/reference/ + if-no-files-found: error + retention-days: 1 + + next: + runs-on: ubuntu-latest + concurrency: + group: next-reference-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + env: + CI: true + NODE_OPTIONS: --max-old-space-size=8192 + + steps: + - name: Harden Runner + uses: step-security/harden-runner@5c7944e73c4c2a096b17a9cb74d65b6c2bbafbde # v2.9.1 + with: + egress-policy: audit + + - name: checkout master + uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7 + + - name: use node.js 18.x + uses: actions/setup-node@1e60f620b9541d16bece96c5465dc8ee9832be0b # v4.0.3 + with: + node-version: 18.x + registry-url: https://registry.npmjs.org/ # Needed for auth + + - name: yarn install + uses: backstage/actions/yarn-install@3c138326f7fcbf253b88170c1f29bae8e975d47c # v0.6.14 + with: + cache-prefix: ${{ runner.os }}-v18.x + + - name: build API reference + run: yarn build:api-docs + + - name: upload API reference + uses: actions/upload-artifact@v4 + with: + name: next-reference + path: docs/reference/ + if-no-files-found: error + retention-days: 1 + + # Also build and upload storybook + - name: storybook yarn install + run: yarn install --immutable + working-directory: storybook + + - name: storybook build + run: yarn build-storybook + working-directory: storybook + + - name: storybook upload + uses: actions/upload-artifact@v4 + with: + name: storybook + path: storybook/dist/ + if-no-files-found: error + retention-days: 1 + + deploy-microsite-and-storybook: + permissions: + contents: write # for JamesIves/github-pages-deploy-action to push changes in repo + + runs-on: ubuntu-latest + + needs: + - stable + - next + + env: + CI: true + NODE_OPTIONS: --max-old-space-size=16384 DOCUSAURUS_SSR_CONCURRENCY: 5 concurrency: @@ -28,39 +162,59 @@ jobs: with: egress-policy: audit - - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7 - - name: use node.js 18.x uses: actions/setup-node@1e60f620b9541d16bece96c5465dc8ee9832be0b # v4.0.3 with: node-version: 18.x registry-url: https://registry.npmjs.org/ # Needed for auth - # We avoid caching in this workflow, as we're running an install of both the top-level - # dependencies and the microsite. We leave it to the main master workflow to produce the - # cache, as that results in a smaller bundle. - - name: top-level yarn install - run: yarn install --immutable + # Stable docs + - name: checkout latest release + uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7 + with: + ref: refs/tags/${{ needs.stable.outputs.release }} + - name: microsite yarn install run: yarn install --immutable working-directory: microsite - - name: storybook yarn install - run: yarn install --immutable - working-directory: storybook - - name: build API reference - run: yarn build:api-docs + - name: download stable reference + uses: actions/download-artifact@v4 + with: + name: stable-reference + path: docs/reference + + - name: generate stable docs + run: yarn docusaurus docs:version stable + working-directory: microsite + + - name: clear API reference + run: rm -r docs/reference + + # Next docs + - name: checkout master + uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7 + with: + clean: false + + - name: microsite yarn install + run: yarn install --immutable + working-directory: microsite + + - name: download next reference + uses: actions/download-artifact@v4 + with: + name: next-reference + path: docs/reference - name: build microsite run: yarn build working-directory: microsite - - name: build storybook - run: yarn build-storybook - working-directory: storybook - - - name: move storybook dist into microsite - run: mv storybook/dist/ microsite/build/storybook + - uses: actions/download-artifact@v4 + with: + name: storybook + path: microsite/build/storybook - name: Check the build output run: ls microsite/build && ls microsite/build/storybook diff --git a/.gitignore b/.gitignore index 6db4bf549c..865918c1f7 100644 --- a/.gitignore +++ b/.gitignore @@ -42,6 +42,9 @@ coverage # Bower dependency directory (https://bower.io/) bower_components +# Documentation reference, generated by build:api-docs +docs/reference + # node-waf configuration .lock-wscript diff --git a/docs/.gitignore b/docs/.gitignore deleted file mode 100644 index 90b1e2c7ef..0000000000 --- a/docs/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -# This is generated by build:api-docs in the root -reference diff --git a/microsite/docusaurus.config.ts b/microsite/docusaurus.config.ts index a6909f139f..96edb57dea 100644 --- a/microsite/docusaurus.config.ts +++ b/microsite/docusaurus.config.ts @@ -21,9 +21,38 @@ import { themes } from 'prism-react-renderer'; import type * as Preset from '@docusaurus/preset-classic'; import { Config } from '@docusaurus/types'; +import RedirectPlugin from '@docusaurus/plugin-client-redirects'; + const backstageTheme = themes.vsDark; backstageTheme.plain.backgroundColor = '#232323'; +const useVersionedDocs = require('fs').existsSync('versions.json'); + +// This patches the redirect plugin to ignore the error when it tries to override existing fields. +// This lets us add redirects that only apply to the next docs, while the stable docs still contain the source path. +const PatchedRedirectPlugin: typeof RedirectPlugin = (ctx, opts) => { + const plugin = RedirectPlugin(ctx, opts); + + return { + ...plugin, + async postBuild(...args) { + try { + await plugin.postBuild(...args); + } catch (error) { + if ( + error.message === + 'The redirect plugin is not supposed to override existing files.' + ) { + // Bit of a hack to make sure all remaining redirects are written, since the write uses Promise.all + await new Promise(resolve => setTimeout(resolve, 1000)); + } else { + throw error; + } + } + }, + }; +}; + const config: Config = { title: 'Backstage Software Catalog and Developer Platform', tagline: 'An open source framework for building developer portals', @@ -57,6 +86,26 @@ const config: Config = { editUrl: 'https://github.com/backstage/backstage/edit/master/docs/', path: '../docs', sidebarPath: 'sidebars.json', + ...(useVersionedDocs + ? { + includeCurrentVersion: true, + lastVersion: 'stable', + versions: { + stable: { + label: 'Stable', + path: '/', + banner: 'none', + badge: false, + }, + current: { + label: 'Next', + path: '/next', + banner: 'unreleased', + badge: true, + }, + }, + } + : undefined), }, blog: { path: 'blog', @@ -119,9 +168,11 @@ const config: Config = { }; }, }), - [ - '@docusaurus/plugin-client-redirects', - { + ctx => + PatchedRedirectPlugin(ctx, { + id: '@docusaurus/plugin-client-redirects', + toExtensions: [], + fromExtensions: [], redirects: [ { from: '/docs', @@ -200,8 +251,7 @@ const config: Config = { to: '/docs/backend-system/core-services/url-reader', }, ], - }, - ], + }), [ 'docusaurus-pushfeedback', { @@ -259,6 +309,14 @@ const config: Config = { label: 'Community', position: 'left', }, + ...(useVersionedDocs + ? [ + { + type: 'docsVersionDropdown', + position: 'right' as const, + }, + ] + : []), ], }, image: 'img/sharing-opengraph.png', diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 6038229bf0..d134486024 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -1,39 +1,4 @@ { - "releases": { - "Release Notes": [ - "releases/v1.30.0", - "releases/v1.29.0", - "releases/v1.28.0", - "releases/v1.27.0", - "releases/v1.26.0", - "releases/v1.25.0", - "releases/v1.24.0", - "releases/v1.23.0", - "releases/v1.22.0", - "releases/v1.21.0", - "releases/v1.20.0", - "releases/v1.19.0", - "releases/v1.18.0", - "releases/v1.17.0", - "releases/v1.16.0", - "releases/v1.15.0", - "releases/v1.14.0", - "releases/v1.13.0", - "releases/v1.12.0", - "releases/v1.11.0", - "releases/v1.10.0", - "releases/v1.9.0", - "releases/v1.8.0", - "releases/v1.7.0", - "releases/v1.6.0", - "releases/v1.5.0", - "releases/v1.4.0", - "releases/v1.3.0", - "releases/v1.2.0", - "releases/v1.1.0", - "releases/v1.0.0" - ] - }, "docs": { "Overview": [ "overview/what-is-backstage", @@ -556,5 +521,40 @@ "contribute/project-structure" ], "References": ["references/glossary"] + }, + "releases": { + "Release Notes": [ + "releases/v1.30.0", + "releases/v1.29.0", + "releases/v1.28.0", + "releases/v1.27.0", + "releases/v1.26.0", + "releases/v1.25.0", + "releases/v1.24.0", + "releases/v1.23.0", + "releases/v1.22.0", + "releases/v1.21.0", + "releases/v1.20.0", + "releases/v1.19.0", + "releases/v1.18.0", + "releases/v1.17.0", + "releases/v1.16.0", + "releases/v1.15.0", + "releases/v1.14.0", + "releases/v1.13.0", + "releases/v1.12.0", + "releases/v1.11.0", + "releases/v1.10.0", + "releases/v1.9.0", + "releases/v1.8.0", + "releases/v1.7.0", + "releases/v1.6.0", + "releases/v1.5.0", + "releases/v1.4.0", + "releases/v1.3.0", + "releases/v1.2.0", + "releases/v1.1.0", + "releases/v1.0.0" + ] } }