From 97a726e0bb5b1615b4e1dffe899945398d5e5874 Mon Sep 17 00:00:00 2001 From: aramissennyeydd Date: Sun, 9 Nov 2025 16:25:48 -0500 Subject: [PATCH 1/4] chore: disable old api reference generation Signed-off-by: aramissennyeydd --- .github/workflows/deploy_microsite.yml | 40 ++++++-------------------- microsite/package.json | 2 +- microsite/scripts/pre-build.js | 39 ------------------------- 3 files changed, 10 insertions(+), 71 deletions(-) delete mode 100644 microsite/scripts/pre-build.js diff --git a/.github/workflows/deploy_microsite.yml b/.github/workflows/deploy_microsite.yml index 08f349c7ec..b403b0af9a 100644 --- a/.github/workflows/deploy_microsite.yml +++ b/.github/workflows/deploy_microsite.yml @@ -69,17 +69,6 @@ jobs: with: cache-prefix: ${{ runner.os }}-v22.x - - name: build API reference - run: yarn build:api-docs - - - name: upload API reference - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 - with: - name: stable-reference - path: docs/reference/ - if-no-files-found: error - retention-days: 1 - # Use the lower-level cache actions for the success cache, so that we can store the cache even on failed builds - name: restore package-docs cache uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 @@ -89,13 +78,13 @@ jobs: restore-keys: | ${{ runner.os }}-v${{ matrix.node-version }}-package-docs-stable- - - name: build API reference (beta) + - name: build API reference run: yarn backstage-repo-tools package-docs - - name: upload API reference (beta) + - name: upload API reference uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 with: - name: stable-reference-beta + name: stable-reference path: type-docs/ if-no-files-found: error retention-days: 1 @@ -153,17 +142,6 @@ jobs: with: cache-prefix: ${{ runner.os }}-v22.x - - name: build API reference - run: yarn build:api-docs - - - name: upload API reference - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 - with: - name: next-reference - path: docs/reference/ - if-no-files-found: error - retention-days: 1 - # Use the lower-level cache actions for the success cache, so that we can store the cache even on failed builds - name: restore package-docs cache uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 @@ -173,13 +151,13 @@ jobs: restore-keys: | ${{ runner.os }}-v${{ matrix.node-version }}-package-docs- - - name: build API reference (beta) + - name: build API reference run: yarn backstage-repo-tools package-docs - - name: upload API reference (beta) + - name: upload API reference uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 with: - name: next-reference-beta + name: next-reference path: type-docs/ if-no-files-found: error retention-days: 1 @@ -317,12 +295,12 @@ jobs: - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4 with: - name: stable-reference-beta - path: microsite/build/api/stable/ + name: stable-reference + path: microsite/build/api/ - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4 with: - name: next-reference-beta + name: next-reference path: microsite/build/api/next/ - name: Check the build output diff --git a/microsite/package.json b/microsite/package.json index edf07abb02..fd727ef1bb 100644 --- a/microsite/package.json +++ b/microsite/package.json @@ -4,7 +4,7 @@ "private": true, "license": "Apache-2.0", "scripts": { - "build": "node scripts/pre-build.js && docusaurus build", + "build": "docusaurus build", "deploy": "docusaurus deploy", "docusaurus": "docusaurus", "generate-openapi-docs": "yarn docusaurus clean-api-docs all && yarn docusaurus gen-api-docs all", diff --git a/microsite/scripts/pre-build.js b/microsite/scripts/pre-build.js deleted file mode 100644 index 3b5bd4fb0b..0000000000 --- a/microsite/scripts/pre-build.js +++ /dev/null @@ -1,39 +0,0 @@ -/* - * Copyright 2022 The Backstage Authors - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -const { existsSync, writeFileSync, mkdirSync } = require('fs'); -const path = require('path'); - -const PLACEHOLDER = `--- -id: "index" -title: "Package Index" -description: "Index of all Backstage Packages" ---- -Run \`yarn build:api-docs\` to generate the API docs. -`; - -async function main() { - const referencesDir = '../docs/reference'; - if (!existsSync(referencesDir)) { - mkdirSync(referencesDir); - writeFileSync(path.join(referencesDir, 'index.md'), PLACEHOLDER); - } -} - -main().catch(error => { - console.error(error.stack); - process.exit(1); -}); From 14a8190e1696e9cf5120e636ae0199bab2e307aa Mon Sep 17 00:00:00 2001 From: aramissennyeydd Date: Sun, 9 Nov 2025 16:36:16 -0500 Subject: [PATCH 2/4] fix verify workflow too Signed-off-by: aramissennyeydd add back prebuild script Signed-off-by: aramissennyeydd fix script location Signed-off-by: aramissennyeydd skip techdocs Signed-off-by: aramissennyeydd make references/index tracked in git Signed-off-by: aramissennyeydd don't try to build with new reference docs Signed-off-by: aramissennyeydd fix redirect Signed-off-by: aramissennyeydd disable redirect Signed-off-by: aramissennyeydd --- .github/workflows/deploy_microsite.yml | 14 +----- .github/workflows/verify_microsite.yml | 65 ++++---------------------- docs/references/index.md | 7 +++ microsite/package.json | 2 +- 4 files changed, 17 insertions(+), 71 deletions(-) create mode 100644 docs/references/index.md diff --git a/.github/workflows/deploy_microsite.yml b/.github/workflows/deploy_microsite.yml index b403b0af9a..78ae43c637 100644 --- a/.github/workflows/deploy_microsite.yml +++ b/.github/workflows/deploy_microsite.yml @@ -238,12 +238,6 @@ jobs: run: yarn install --immutable working-directory: microsite - - name: download stable reference - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4 - with: - name: stable-reference - path: docs/reference - - name: download stable OpenAPI API docs uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4 with: @@ -272,12 +266,6 @@ jobs: run: yarn install --immutable working-directory: microsite - - name: download next reference - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4 - with: - name: next-reference - path: docs/reference - - name: download next OpenAPI API docs uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4 with: @@ -296,7 +284,7 @@ jobs: - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4 with: name: stable-reference - path: microsite/build/api/ + path: microsite/build/api/stable/ - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4 with: diff --git a/.github/workflows/verify_microsite.yml b/.github/workflows/verify_microsite.yml index 20a6e705cd..b3c8a45172 100644 --- a/.github/workflows/verify_microsite.yml +++ b/.github/workflows/verify_microsite.yml @@ -74,17 +74,6 @@ jobs: with: cache-prefix: ${{ runner.os }}-v22.x - - name: build API reference - run: yarn build:api-docs - - - name: upload API reference - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 - with: - name: stable-reference - path: docs/reference/ - if-no-files-found: error - retention-days: 1 - # Use the lower-level cache actions for the success cache, so that we can store the cache even on failed builds - name: restore package-docs cache uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 @@ -94,13 +83,13 @@ jobs: restore-keys: | ${{ runner.os }}-v${{ matrix.node-version }}-package-docs-stable- - - name: build API reference (beta) + - name: build API reference run: yarn backstage-repo-tools package-docs - - name: upload API reference (beta) + - name: upload API reference uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 with: - name: stable-reference-beta + name: stable-reference path: type-docs/ # Always save success cache even if there were failures, that way it can be used in re-triggered builds @@ -155,17 +144,6 @@ jobs: with: cache-prefix: ${{ runner.os }}-v22.x - - name: build API reference - run: yarn build:api-docs - - - name: upload API reference - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 - with: - name: next-reference - path: docs/reference/ - if-no-files-found: error - retention-days: 1 - # Use the lower-level cache actions for the success cache, so that we can store the cache even on failed builds - name: restore package-docs cache uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 @@ -175,13 +153,13 @@ jobs: restore-keys: | ${{ runner.os }}-v${{ matrix.node-version }}-package-docs-next- - - name: build API reference (beta) + - name: build API reference run: yarn backstage-repo-tools package-docs - - name: upload API reference (beta) + - name: upload API reference uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 with: - name: next-reference-beta + name: next-reference path: type-docs/ # Always save success cache even if there were failures, that way it can be used in re-triggered builds @@ -267,12 +245,6 @@ jobs: - name: verify yarn dependency duplicates run: node scripts/verify-lockfile-duplicates.js - - name: download stable reference - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4 - with: - name: stable-reference - path: docs/reference - - name: download stable OpenAPI API docs uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4 with: @@ -291,22 +263,13 @@ jobs: - name: clear generated docs run: git clean -fdx docs/ - - name: build API reference - run: yarn build:api-docs - - name: checkout master uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 with: clean: false - - name: Build MkDocs for TechDocs - run: mkdocs build --strict - - - name: download next reference - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4 - with: - name: next-reference - path: docs/reference + # - name: Build MkDocs for TechDocs + # run: mkdocs build --strict - name: download next OpenAPI API docs uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4 @@ -317,15 +280,3 @@ jobs: - name: build microsite run: yarn build working-directory: microsite - - - name: download stable reference (beta) - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4 - with: - name: stable-reference-beta - path: api/stable/ - - - name: download next reference (beta) - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4 - with: - name: next-reference-beta - path: api/next/ diff --git a/docs/references/index.md b/docs/references/index.md new file mode 100644 index 0000000000..abd5c99c0c --- /dev/null +++ b/docs/references/index.md @@ -0,0 +1,7 @@ +--- +id: 'index' +title: 'Package Index' +description: 'Index of all Backstage Packages' +--- + +Please use [the new API documentation](https://backstage.io/api/stable) for more information. diff --git a/microsite/package.json b/microsite/package.json index fd727ef1bb..8087d96b19 100644 --- a/microsite/package.json +++ b/microsite/package.json @@ -12,7 +12,7 @@ "prettier:fix": "prettier --write .", "publish-gh-pages": "docusaurus-publish", "rename-version": "docusaurus-rename-version", - "start": "node scripts/pre-build.js && docusaurus start", + "start": "docusaurus start", "swizzle": "docusaurus swizzle", "verify:sidebars": "node ./scripts/verify-sidebars", "version": "docusaurus-version", From 9fd02a4e12bf80e22f7903bde51d233da6ec1cb3 Mon Sep 17 00:00:00 2001 From: aramissennyeydd Date: Thu, 18 Dec 2025 08:48:15 -0700 Subject: [PATCH 3/4] fix sidebar conflict Signed-off-by: aramissennyeydd --- microsite/sidebars.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/microsite/sidebars.ts b/microsite/sidebars.ts index afe5616bbf..b30ffddc2a 100644 --- a/microsite/sidebars.ts +++ b/microsite/sidebars.ts @@ -751,7 +751,7 @@ export default { 'api/deprecations', 'references/glossary', 'api/utility-apis', - 'reference/index', + 'references/index', ], ), ], From 3c8a824bb6699bd7f33801f6add685dfa89d9f68 Mon Sep 17 00:00:00 2001 From: aramissennyeydd Date: Sat, 20 Dec 2025 20:36:39 -0700 Subject: [PATCH 4/4] add back strict build Signed-off-by: aramissennyeydd --- .github/workflows/verify_microsite.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/verify_microsite.yml b/.github/workflows/verify_microsite.yml index b3c8a45172..0145475121 100644 --- a/.github/workflows/verify_microsite.yml +++ b/.github/workflows/verify_microsite.yml @@ -268,8 +268,8 @@ jobs: with: clean: false - # - name: Build MkDocs for TechDocs - # run: mkdocs build --strict + - name: Build MkDocs for TechDocs + run: mkdocs build --strict - name: download next OpenAPI API docs uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4