From 9f39fe7d89f8da87fe710f5090b9634ca1cf28b8 Mon Sep 17 00:00:00 2001 From: blam Date: Tue, 10 Sep 2024 15:34:29 +0200 Subject: [PATCH 1/6] chore: move sidebar to .mjs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fredrik Adelöw Co-authored-by: Camila Belo Co-authored-by: Patrik Oldsberg Co-authored-by: Johan Haals :wq Signed-off-by: blam --- microsite/docusaurus.config.ts | 2 +- microsite/sidebars.json | 561 --------------------------------- microsite/sidebars.mjs | 548 ++++++++++++++++++++++++++++++++ 3 files changed, 549 insertions(+), 562 deletions(-) delete mode 100644 microsite/sidebars.json create mode 100644 microsite/sidebars.mjs diff --git a/microsite/docusaurus.config.ts b/microsite/docusaurus.config.ts index 96edb57dea..8f4c08f8e9 100644 --- a/microsite/docusaurus.config.ts +++ b/microsite/docusaurus.config.ts @@ -85,7 +85,7 @@ const config: Config = { docs: { editUrl: 'https://github.com/backstage/backstage/edit/master/docs/', path: '../docs', - sidebarPath: 'sidebars.json', + sidebarPath: 'sidebars.mjs', ...(useVersionedDocs ? { includeCurrentVersion: true, diff --git a/microsite/sidebars.json b/microsite/sidebars.json deleted file mode 100644 index 4d3761c27d..0000000000 --- a/microsite/sidebars.json +++ /dev/null @@ -1,561 +0,0 @@ -{ - "docs": { - "Overview": [ - "overview/what-is-backstage", - "overview/architecture-overview", - "overview/roadmap", - "overview/vision", - "overview/background", - "overview/adopting", - "overview/versioning-policy", - "overview/threat-model", - "overview/support", - "overview/logos" - ], - "Getting Started": [ - "getting-started/index", - { - "type": "category", - "label": "Configuring Backstage", - "items": [ - "getting-started/config/database", - "getting-started/config/authentication", - "getting-started/configure-app-with-plugins", - "getting-started/app-custom-theme", - "getting-started/homepage" - ] - }, - { - "type": "category", - "label": "Using Backstage", - "items": [ - "getting-started/logging-in", - "getting-started/register-a-component", - "getting-started/create-a-component" - ] - }, - "getting-started/keeping-backstage-updated", - "getting-started/concepts" - ], - "Core Features": [ - { - "type": "category", - "label": "Software Catalog", - "items": [ - "features/software-catalog/software-catalog-overview", - "features/software-catalog/life-of-an-entity", - "features/software-catalog/configuration", - "features/software-catalog/system-model", - "features/software-catalog/descriptor-format", - "features/software-catalog/references", - "features/software-catalog/well-known-annotations", - "features/software-catalog/well-known-relations", - "features/software-catalog/well-known-statuses", - "features/software-catalog/extending-the-model", - "features/software-catalog/external-integrations", - "features/software-catalog/catalog-customization", - "features/software-catalog/software-catalog-api", - "features/software-catalog/creating-the-catalog-graph", - "features/software-catalog/faq" - ] - }, - { - "type": "category", - "label": "Kubernetes", - "items": [ - "features/kubernetes/overview", - "features/kubernetes/installation", - "features/kubernetes/configuration", - "features/kubernetes/authentication", - "features/kubernetes/authentication-strategies", - "features/kubernetes/troubleshooting", - "features/kubernetes/proxy" - ] - }, - { - "type": "category", - "label": "Software Templates", - "items": [ - "features/software-templates/software-templates-index", - "features/software-templates/configuration", - "features/software-templates/adding-templates", - "features/software-templates/writing-templates", - "features/software-templates/input-examples", - "features/software-templates/builtin-actions", - "features/software-templates/writing-custom-actions", - "features/software-templates/writing-tests-for-actions", - "features/software-templates/writing-custom-field-extensions", - "features/software-templates/writing-custom-step-layouts", - "features/software-templates/authorizing-scaffolder-template-details", - "features/software-templates/migrating-to-rjsf-v5", - "features/software-templates/migrating-from-v1beta2-to-v1beta3", - "features/software-templates/dry-run-testing" - ] - }, - { - "type": "category", - "label": "Backstage Search", - "items": [ - "features/search/search-overview", - "features/search/getting-started", - "features/search/concepts", - "features/search/architecture", - "features/search/search-engines", - "features/search/collators", - "features/search/how-to-guides" - ] - }, - { - "type": "category", - "label": "TechDocs", - "items": [ - "features/techdocs/techdocs-overview", - "features/techdocs/getting-started", - "features/techdocs/concepts", - "features/techdocs/addons", - "features/techdocs/architecture", - "features/techdocs/creating-and-publishing", - "features/techdocs/configuration", - "features/techdocs/using-cloud-storage", - "features/techdocs/configuring-ci-cd", - "features/techdocs/cli", - "features/techdocs/how-to-guides", - "features/techdocs/troubleshooting", - "features/techdocs/faqs" - ] - } - ], - "Integrations": [ - "integrations/index", - { - "type": "category", - "label": "AWS S3", - "items": [ - "integrations/aws-s3/locations", - "integrations/aws-s3/discovery" - ] - }, - { - "type": "category", - "label": "Azure", - "items": [ - "integrations/azure/locations", - "integrations/azure/discovery", - "integrations/azure/org" - ] - }, - { - "type": "category", - "label": "Bitbucket Cloud", - "items": [ - "integrations/bitbucketCloud/locations", - "integrations/bitbucketCloud/discovery" - ] - }, - { - "type": "category", - "label": "Bitbucket Server", - "items": [ - "integrations/bitbucketServer/locations", - "integrations/bitbucketServer/discovery" - ] - }, - { - "type": "category", - "label": "Datadog", - "items": ["integrations/datadog-rum/installation"] - }, - { - "type": "category", - "label": "Gerrit", - "items": [ - "integrations/gerrit/locations", - "integrations/gerrit/discovery" - ] - }, - { - "type": "category", - "label": "GitHub", - "items": [ - "integrations/github/locations", - "integrations/github/discovery", - "integrations/github/org", - "integrations/github/github-apps" - ] - }, - { - "type": "category", - "label": "GitLab", - "items": [ - "integrations/gitlab/locations", - "integrations/gitlab/discovery", - "integrations/gitlab/org" - ] - }, - { - "type": "category", - "label": "Gitea", - "items": ["integrations/gitea/locations"] - }, - { - "type": "category", - "label": "Harness", - "items": ["integrations/harness/locations"] - }, - { - "type": "category", - "label": "Google GCS", - "items": ["integrations/google-cloud-storage/locations"] - }, - { - "type": "category", - "label": "LDAP", - "items": ["integrations/ldap/org"] - } - ], - "Plugins": [ - "plugins/index", - "plugins/existing-plugins", - "plugins/create-a-plugin", - "plugins/plugin-development", - "plugins/structure-of-a-plugin", - "plugins/integrating-plugin-into-software-catalog", - "plugins/integrating-search-into-plugins", - "plugins/composability", - "plugins/internationalization", - "plugins/analytics", - "plugins/feature-flags", - { - "type": "category", - "label": "OpenAPI", - "items": [ - "openapi/01-getting-started", - "openapi/generate-client", - "openapi/test-case-validation" - ] - }, - { - "type": "category", - "label": "Backends and APIs", - "items": [ - "plugins/proxying", - "plugins/backend-plugin", - "plugins/call-existing-api" - ] - }, - { - "type": "category", - "label": "Testing", - "items": ["plugins/testing"] - }, - { - "type": "category", - "label": "Publishing", - "items": [ - "plugins/publish-private", - "plugins/add-to-directory", - "plugins/observability" - ] - } - ], - "Configuration": [ - "conf/index", - "conf/reading", - "conf/writing", - "conf/defining" - ], - "Notifications": ["notifications/index"], - "Auth and identity": [ - "auth/index", - { - "type": "category", - "label": "Included providers", - "items": [ - "auth/auth0/provider", - "auth/atlassian/provider", - "auth/aws-alb/provider", - "auth/microsoft/provider", - "auth/microsoft/easy-auth", - "auth/bitbucket/provider", - "auth/bitbucketServer/provider", - "auth/cloudflare/provider", - "auth/github/provider", - "auth/gitlab/provider", - "auth/google/provider", - "auth/google/gcp-iap-auth", - "auth/guest/provider", - "auth/okta/provider", - "auth/oauth2-proxy/provider", - "auth/onelogin/provider", - "auth/vmware-cloud/provider" - ] - }, - "auth/identity-resolver", - "auth/oauth", - "auth/oidc", - "auth/add-auth-provider", - "auth/service-to-service-auth", - "auth/autologout", - "auth/troubleshooting" - ], - "Permissions": [ - "permissions/overview", - "permissions/concepts", - "permissions/getting-started", - "permissions/writing-a-policy", - "permissions/frontend-integration", - "permissions/custom-rules", - { - "type": "category", - "label": "Tutorial: using Permissions in your plugin", - "items": [ - "permissions/plugin-authors/01-setup", - "permissions/plugin-authors/02-adding-a-basic-permission-check", - "permissions/plugin-authors/03-adding-a-resource-permission-check", - "permissions/plugin-authors/04-authorizing-access-to-paginated-data", - "permissions/plugin-authors/05-frontend-authorization" - ] - } - ], - "Tooling": [ - { - "type": "category", - "label": "Backstage CLI", - "items": [ - "tooling/cli/overview", - "tooling/cli/build-system", - "tooling/cli/commands" - ] - }, - { - "type": "category", - "label": "Local Development", - "items": [ - "tooling/local-dev/linking-local-packages", - "tooling/local-dev/debugging", - "tooling/local-dev/profiling" - ] - }, - "tooling/package-metadata" - ], - "Deployment": [ - "deployment/index", - "deployment/scaling", - "deployment/docker", - "deployment/k8s", - "deployment/heroku", - "deployment/koyeb", - "deployment/flightcontrol", - { - "type": "category", - "label": "Using Backstage Deploy (alpha)", - "items": ["deployment/backstage-deploy/aws-lightsail"] - } - ], - "New Backend System": [ - "backend-system/index", - { - "type": "category", - "label": "Architecture", - "items": [ - "backend-system/architecture/index", - "backend-system/architecture/services", - "backend-system/architecture/plugins", - "backend-system/architecture/extension-points", - "backend-system/architecture/modules", - "backend-system/architecture/feature-loaders", - "backend-system/architecture/naming-patterns" - ] - }, - { - "type": "category", - "label": "Building Backends", - "items": [ - "backend-system/building-backends/index", - "backend-system/building-backends/migrating" - ] - }, - { - "type": "category", - "label": "Building Plugins & Modules", - "items": [ - "backend-system/building-plugins-and-modules/index", - "backend-system/building-plugins-and-modules/testing", - "backend-system/building-plugins-and-modules/migrating" - ] - }, - { - "type": "category", - "label": "Core Services", - "items": [ - "backend-system/core-services/index", - "backend-system/core-services/auth", - "backend-system/core-services/cache", - "backend-system/core-services/database", - "backend-system/core-services/discovery", - "backend-system/core-services/http-auth", - "backend-system/core-services/http-router", - "backend-system/core-services/identity", - "backend-system/core-services/lifecycle", - "backend-system/core-services/logger", - "backend-system/core-services/permissions", - "backend-system/core-services/plugin-metadata", - "backend-system/core-services/root-config", - "backend-system/core-services/root-health", - "backend-system/core-services/root-http-router", - "backend-system/core-services/root-lifecycle", - "backend-system/core-services/root-logger", - "backend-system/core-services/scheduler", - "backend-system/core-services/token-manager", - "backend-system/core-services/url-reader", - "backend-system/core-services/user-info" - ] - } - ], - "New Frontend System": [ - "frontend-system/index", - { - "type": "category", - "label": "Architecture", - "items": [ - "frontend-system/architecture/index", - "frontend-system/architecture/app", - "frontend-system/architecture/plugins", - "frontend-system/architecture/extensions", - "frontend-system/architecture/extension-blueprints", - "frontend-system/architecture/extension-overrides", - "frontend-system/architecture/references", - "frontend-system/architecture/utility-apis", - "frontend-system/architecture/routes", - "frontend-system/architecture/naming-patterns", - "frontend-system/architecture/migrations" - ] - }, - { - "type": "category", - "label": "Building Plugins", - "items": [ - "frontend-system/building-plugins/index", - "frontend-system/building-plugins/testing", - "frontend-system/building-plugins/common-extension-blueprints", - "frontend-system/building-plugins/built-in-data-refs", - "frontend-system/building-plugins/migrating" - ] - }, - { - "type": "category", - "label": "Building Apps", - "items": [ - "frontend-system/building-apps/index", - "frontend-system/building-apps/configuring-extensions", - "frontend-system/building-apps/built-in-extensions", - "frontend-system/building-apps/plugin-conversion", - "frontend-system/building-apps/migrating" - ] - }, - { - "type": "category", - "label": "Utility APIs", - "items": [ - "frontend-system/utility-apis/index", - "frontend-system/utility-apis/creating", - "frontend-system/utility-apis/consuming", - "frontend-system/utility-apis/configuring" - ] - } - ], - "Designing for Backstage": [ - "dls/design", - "dls/component-design-guidelines", - "dls/contributing-to-storybook", - "dls/figma" - ], - "API Reference": [ - { - "type": "category", - "label": "Guides", - "items": ["api/utility-apis"] - }, - { - "type": "category", - "label": "API Reference", - "items": ["reference/index"] - }, - "api/deprecations" - ], - "Tutorials": [ - "tutorials/quickstart-app-plugin", - "tutorials/react-router-stable-migration", - "tutorials/react18-migration", - "tutorials/package-role-migration", - "tutorials/migrating-away-from-core", - "tutorials/configuring-plugin-databases", - "tutorials/switching-sqlite-postgres", - "tutorials/using-backstage-proxy-within-plugin", - "tutorials/yarn-migration", - "tutorials/migrate-to-mui5", - "tutorials/auth-service-migration", - "tutorials/enable-public-entry", - "tutorials/setup-opentelemetry" - ], - "Architecture Decision Records (ADRs)": [ - "architecture-decisions/adrs-overview", - "architecture-decisions/adrs-adr001", - "architecture-decisions/adrs-adr002", - "architecture-decisions/adrs-adr003", - "architecture-decisions/adrs-adr004", - "architecture-decisions/adrs-adr005", - "architecture-decisions/adrs-adr006", - "architecture-decisions/adrs-adr007", - "architecture-decisions/adrs-adr008", - "architecture-decisions/adrs-adr009", - "architecture-decisions/adrs-adr010", - "architecture-decisions/adrs-adr011", - "architecture-decisions/adrs-adr012", - "architecture-decisions/adrs-adr013" - ], - "FAQ": ["faq/index", "faq/product", "faq/technical"], - "Accessibility": ["accessibility/index"], - "Contribute": [ - "contribute/index", - "contribute/getting-involved", - "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" - ] - } -} diff --git a/microsite/sidebars.mjs b/microsite/sidebars.mjs new file mode 100644 index 0000000000..675f53a7d6 --- /dev/null +++ b/microsite/sidebars.mjs @@ -0,0 +1,548 @@ +import fs from 'node:fs'; +import path from 'node:path'; + +const docsDir = path.resolve( + path.dirname(new URL(import.meta.url).pathname), + '../docs', +); + +const allReleaseDocs = fs.readdirSync(path.resolve(docsDir, 'releases')); +const mainRleases = allReleaseDocs + .filter(doc => doc.match(/^v\d+\.\d+\.\d+\.md$/)) + .map(doc => doc.replace(/\.md$/, '')) + .sort((a, b) => { // Semver sort + const aVal = a.slice(1).split('.').reduce((acc, val) => acc * 1000 + parseInt(val), 0); + const bVal = b.slice(1).split('.').reduce((acc, val) => acc * 1000 + parseInt(val), 0); + return bVal - aVal; + }) + .map(release => `releases/${release}`); + +export default { + docs: { + Overview: [ + 'overview/what-is-backstage', + 'overview/architecture-overview', + 'overview/roadmap', + 'overview/vision', + 'overview/background', + 'overview/adopting', + 'overview/versioning-policy', + 'overview/threat-model', + 'overview/support', + 'overview/logos', + ], + 'Getting Started': [ + 'getting-started/index', + { + type: 'category', + label: 'Configuring Backstage', + items: [ + 'getting-started/config/database', + 'getting-started/config/authentication', + 'getting-started/configure-app-with-plugins', + 'getting-started/app-custom-theme', + 'getting-started/homepage', + ], + }, + { + type: 'category', + label: 'Using Backstage', + items: [ + 'getting-started/logging-in', + 'getting-started/register-a-component', + 'getting-started/create-a-component', + ], + }, + 'getting-started/keeping-backstage-updated', + 'getting-started/concepts', + ], + 'Core Features': [ + { + type: 'category', + label: 'Software Catalog', + items: [ + 'features/software-catalog/software-catalog-overview', + 'features/software-catalog/life-of-an-entity', + 'features/software-catalog/configuration', + 'features/software-catalog/system-model', + 'features/software-catalog/descriptor-format', + 'features/software-catalog/references', + 'features/software-catalog/well-known-annotations', + 'features/software-catalog/well-known-relations', + 'features/software-catalog/well-known-statuses', + 'features/software-catalog/extending-the-model', + 'features/software-catalog/external-integrations', + 'features/software-catalog/catalog-customization', + 'features/software-catalog/software-catalog-api', + 'features/software-catalog/creating-the-catalog-graph', + 'features/software-catalog/faq', + ], + }, + { + type: 'category', + label: 'Kubernetes', + items: [ + 'features/kubernetes/overview', + 'features/kubernetes/installation', + 'features/kubernetes/configuration', + 'features/kubernetes/authentication', + 'features/kubernetes/authentication-strategies', + 'features/kubernetes/troubleshooting', + 'features/kubernetes/proxy', + ], + }, + { + type: 'category', + label: 'Software Templates', + items: [ + 'features/software-templates/software-templates-index', + 'features/software-templates/configuration', + 'features/software-templates/adding-templates', + 'features/software-templates/writing-templates', + 'features/software-templates/input-examples', + 'features/software-templates/builtin-actions', + 'features/software-templates/writing-custom-actions', + 'features/software-templates/writing-tests-for-actions', + 'features/software-templates/writing-custom-field-extensions', + 'features/software-templates/writing-custom-step-layouts', + 'features/software-templates/authorizing-scaffolder-template-details', + 'features/software-templates/migrating-to-rjsf-v5', + 'features/software-templates/migrating-from-v1beta2-to-v1beta3', + 'features/software-templates/dry-run-testing', + ], + }, + { + type: 'category', + label: 'Backstage Search', + items: [ + 'features/search/search-overview', + 'features/search/getting-started', + 'features/search/concepts', + 'features/search/architecture', + 'features/search/search-engines', + 'features/search/collators', + 'features/search/how-to-guides', + ], + }, + { + type: 'category', + label: 'TechDocs', + items: [ + 'features/techdocs/techdocs-overview', + 'features/techdocs/getting-started', + 'features/techdocs/concepts', + 'features/techdocs/addons', + 'features/techdocs/architecture', + 'features/techdocs/creating-and-publishing', + 'features/techdocs/configuration', + 'features/techdocs/using-cloud-storage', + 'features/techdocs/configuring-ci-cd', + 'features/techdocs/cli', + 'features/techdocs/how-to-guides', + 'features/techdocs/troubleshooting', + 'features/techdocs/faqs', + ], + }, + ], + Integrations: [ + 'integrations/index', + { + type: 'category', + label: 'AWS S3', + items: [ + 'integrations/aws-s3/locations', + 'integrations/aws-s3/discovery', + ], + }, + { + type: 'category', + label: 'Azure', + items: [ + 'integrations/azure/locations', + 'integrations/azure/discovery', + 'integrations/azure/org', + ], + }, + { + type: 'category', + label: 'Bitbucket Cloud', + items: [ + 'integrations/bitbucketCloud/locations', + 'integrations/bitbucketCloud/discovery', + ], + }, + { + type: 'category', + label: 'Bitbucket Server', + items: [ + 'integrations/bitbucketServer/locations', + 'integrations/bitbucketServer/discovery', + ], + }, + { + type: 'category', + label: 'Datadog', + items: ['integrations/datadog-rum/installation'], + }, + { + type: 'category', + label: 'Gerrit', + items: [ + 'integrations/gerrit/locations', + 'integrations/gerrit/discovery', + ], + }, + { + type: 'category', + label: 'GitHub', + items: [ + 'integrations/github/locations', + 'integrations/github/discovery', + 'integrations/github/org', + 'integrations/github/github-apps', + ], + }, + { + type: 'category', + label: 'GitLab', + items: [ + 'integrations/gitlab/locations', + 'integrations/gitlab/discovery', + 'integrations/gitlab/org', + ], + }, + { + type: 'category', + label: 'Gitea', + items: ['integrations/gitea/locations'], + }, + { + type: 'category', + label: 'Harness', + items: ['integrations/harness/locations'], + }, + { + type: 'category', + label: 'Google GCS', + items: ['integrations/google-cloud-storage/locations'], + }, + { + type: 'category', + label: 'LDAP', + items: ['integrations/ldap/org'], + }, + ], + Plugins: [ + 'plugins/index', + 'plugins/existing-plugins', + 'plugins/create-a-plugin', + 'plugins/plugin-development', + 'plugins/structure-of-a-plugin', + 'plugins/integrating-plugin-into-software-catalog', + 'plugins/integrating-search-into-plugins', + 'plugins/composability', + 'plugins/internationalization', + 'plugins/analytics', + 'plugins/feature-flags', + { + type: 'category', + label: 'OpenAPI', + items: [ + 'openapi/01-getting-started', + 'openapi/generate-client', + 'openapi/test-case-validation', + ], + }, + { + type: 'category', + label: 'Backends and APIs', + items: [ + 'plugins/proxying', + 'plugins/backend-plugin', + 'plugins/call-existing-api', + ], + }, + { + type: 'category', + label: 'Testing', + items: ['plugins/testing'], + }, + { + type: 'category', + label: 'Publishing', + items: [ + 'plugins/publish-private', + 'plugins/add-to-directory', + 'plugins/observability', + ], + }, + ], + Configuration: [ + 'conf/index', + 'conf/reading', + 'conf/writing', + 'conf/defining', + ], + Notifications: ['notifications/index'], + 'Auth and identity': [ + 'auth/index', + { + type: 'category', + label: 'Included providers', + items: [ + 'auth/auth0/provider', + 'auth/atlassian/provider', + 'auth/aws-alb/provider', + 'auth/microsoft/provider', + 'auth/microsoft/easy-auth', + 'auth/bitbucket/provider', + 'auth/bitbucketServer/provider', + 'auth/cloudflare/provider', + 'auth/github/provider', + 'auth/gitlab/provider', + 'auth/google/provider', + 'auth/google/gcp-iap-auth', + 'auth/guest/provider', + 'auth/okta/provider', + 'auth/oauth2-proxy/provider', + 'auth/onelogin/provider', + 'auth/vmware-cloud/provider', + ], + }, + 'auth/identity-resolver', + 'auth/oauth', + 'auth/oidc', + 'auth/add-auth-provider', + 'auth/service-to-service-auth', + 'auth/autologout', + 'auth/troubleshooting', + ], + Permissions: [ + 'permissions/overview', + 'permissions/concepts', + 'permissions/getting-started', + 'permissions/writing-a-policy', + 'permissions/frontend-integration', + 'permissions/custom-rules', + { + type: 'category', + label: 'Tutorial: using Permissions in your plugin', + items: [ + 'permissions/plugin-authors/01-setup', + 'permissions/plugin-authors/02-adding-a-basic-permission-check', + 'permissions/plugin-authors/03-adding-a-resource-permission-check', + 'permissions/plugin-authors/04-authorizing-access-to-paginated-data', + 'permissions/plugin-authors/05-frontend-authorization', + ], + }, + ], + Tooling: [ + { + type: 'category', + label: 'Backstage CLI', + items: [ + 'tooling/cli/overview', + 'tooling/cli/build-system', + 'tooling/cli/commands', + ], + }, + { + type: 'category', + label: 'Local Development', + items: [ + 'tooling/local-dev/linking-local-packages', + 'tooling/local-dev/debugging', + 'tooling/local-dev/profiling', + ], + }, + 'tooling/package-metadata', + ], + Deployment: [ + 'deployment/index', + 'deployment/scaling', + 'deployment/docker', + 'deployment/k8s', + 'deployment/heroku', + 'deployment/koyeb', + 'deployment/flightcontrol', + { + type: 'category', + label: 'Using Backstage Deploy (alpha)', + items: ['deployment/backstage-deploy/aws-lightsail'], + }, + ], + 'New Backend System': [ + 'backend-system/index', + { + type: 'category', + label: 'Architecture', + items: [ + 'backend-system/architecture/index', + 'backend-system/architecture/services', + 'backend-system/architecture/plugins', + 'backend-system/architecture/extension-points', + 'backend-system/architecture/modules', + 'backend-system/architecture/feature-loaders', + 'backend-system/architecture/naming-patterns', + ], + }, + { + type: 'category', + label: 'Building Backends', + items: [ + 'backend-system/building-backends/index', + 'backend-system/building-backends/migrating', + ], + }, + { + type: 'category', + label: 'Building Plugins & Modules', + items: [ + 'backend-system/building-plugins-and-modules/index', + 'backend-system/building-plugins-and-modules/testing', + 'backend-system/building-plugins-and-modules/migrating', + ], + }, + { + type: 'category', + label: 'Core Services', + items: [ + 'backend-system/core-services/index', + 'backend-system/core-services/auth', + 'backend-system/core-services/cache', + 'backend-system/core-services/database', + 'backend-system/core-services/discovery', + 'backend-system/core-services/http-auth', + 'backend-system/core-services/http-router', + 'backend-system/core-services/identity', + 'backend-system/core-services/lifecycle', + 'backend-system/core-services/logger', + 'backend-system/core-services/permissions', + 'backend-system/core-services/plugin-metadata', + 'backend-system/core-services/root-config', + 'backend-system/core-services/root-health', + 'backend-system/core-services/root-http-router', + 'backend-system/core-services/root-lifecycle', + 'backend-system/core-services/root-logger', + 'backend-system/core-services/scheduler', + 'backend-system/core-services/token-manager', + 'backend-system/core-services/url-reader', + 'backend-system/core-services/user-info', + ], + }, + ], + 'New Frontend System': [ + 'frontend-system/index', + { + type: 'category', + label: 'Architecture', + items: [ + 'frontend-system/architecture/index', + 'frontend-system/architecture/app', + 'frontend-system/architecture/plugins', + 'frontend-system/architecture/extensions', + 'frontend-system/architecture/extension-blueprints', + 'frontend-system/architecture/extension-overrides', + 'frontend-system/architecture/references', + 'frontend-system/architecture/utility-apis', + 'frontend-system/architecture/routes', + 'frontend-system/architecture/naming-patterns', + 'frontend-system/architecture/migrations', + ], + }, + { + type: 'category', + label: 'Building Plugins', + items: [ + 'frontend-system/building-plugins/index', + 'frontend-system/building-plugins/testing', + 'frontend-system/building-plugins/common-extension-blueprints', + 'frontend-system/building-plugins/built-in-data-refs', + 'frontend-system/building-plugins/migrating', + ], + }, + { + type: 'category', + label: 'Building Apps', + items: [ + 'frontend-system/building-apps/index', + 'frontend-system/building-apps/configuring-extensions', + 'frontend-system/building-apps/built-in-extensions', + 'frontend-system/building-apps/plugin-conversion', + 'frontend-system/building-apps/migrating', + ], + }, + { + type: 'category', + label: 'Utility APIs', + items: [ + 'frontend-system/utility-apis/index', + 'frontend-system/utility-apis/creating', + 'frontend-system/utility-apis/consuming', + 'frontend-system/utility-apis/configuring', + ], + }, + ], + 'Designing for Backstage': [ + 'dls/design', + 'dls/component-design-guidelines', + 'dls/contributing-to-storybook', + 'dls/figma', + ], + 'API Reference': [ + { + type: 'category', + label: 'Guides', + items: ['api/utility-apis'], + }, + { + type: 'category', + label: 'API Reference', + items: ['reference/index'], + }, + 'api/deprecations', + ], + Tutorials: [ + 'tutorials/quickstart-app-plugin', + 'tutorials/react-router-stable-migration', + 'tutorials/react18-migration', + 'tutorials/package-role-migration', + 'tutorials/migrating-away-from-core', + 'tutorials/configuring-plugin-databases', + 'tutorials/switching-sqlite-postgres', + 'tutorials/using-backstage-proxy-within-plugin', + 'tutorials/yarn-migration', + 'tutorials/migrate-to-mui5', + 'tutorials/auth-service-migration', + 'tutorials/enable-public-entry', + 'tutorials/setup-opentelemetry', + ], + 'Architecture Decision Records (ADRs)': [ + 'architecture-decisions/adrs-overview', + 'architecture-decisions/adrs-adr001', + 'architecture-decisions/adrs-adr002', + 'architecture-decisions/adrs-adr003', + 'architecture-decisions/adrs-adr004', + 'architecture-decisions/adrs-adr005', + 'architecture-decisions/adrs-adr006', + 'architecture-decisions/adrs-adr007', + 'architecture-decisions/adrs-adr008', + 'architecture-decisions/adrs-adr009', + 'architecture-decisions/adrs-adr010', + 'architecture-decisions/adrs-adr011', + 'architecture-decisions/adrs-adr012', + 'architecture-decisions/adrs-adr013', + ], + FAQ: ['faq/index', 'faq/product', 'faq/technical'], + Accessibility: ['accessibility/index'], + Contribute: [ + 'contribute/index', + 'contribute/getting-involved', + 'contribute/project-structure', + ], + References: ['references/glossary'], + }, + releases: { + 'Release Notes': mainRleases + }, +}; From 64214c690bb6ec0a669c2e8ce49bf6b9c0039772 Mon Sep 17 00:00:00 2001 From: blam Date: Tue, 10 Sep 2024 15:45:11 +0200 Subject: [PATCH 2/6] chore: move some things to typescript Signed-off-by: blam --- microsite/docusaurus.config.ts | 5 +++-- microsite/releases.ts | 24 ++++++++++++++++++++++++ microsite/{sidebars.mjs => sidebars.ts} | 21 ++------------------- microsite/tsconfig.json | 1 + 4 files changed, 30 insertions(+), 21 deletions(-) create mode 100644 microsite/releases.ts rename microsite/{sidebars.mjs => sidebars.ts} (96%) diff --git a/microsite/docusaurus.config.ts b/microsite/docusaurus.config.ts index 8f4c08f8e9..726a1fbf48 100644 --- a/microsite/docusaurus.config.ts +++ b/microsite/docusaurus.config.ts @@ -22,6 +22,7 @@ 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'; +import { releases } from './releases'; const backstageTheme = themes.vsDark; backstageTheme.plain.backgroundColor = '#232323'; @@ -85,7 +86,7 @@ const config: Config = { docs: { editUrl: 'https://github.com/backstage/backstage/edit/master/docs/', path: '../docs', - sidebarPath: 'sidebars.mjs', + sidebarPath: 'sidebars.ts', ...(useVersionedDocs ? { includeCurrentVersion: true, @@ -295,7 +296,7 @@ const config: Config = { position: 'left', }, { - to: 'docs/releases/v1.30.0', + to: `docs/releases/${releases[0]}`, label: 'Releases', position: 'left', }, diff --git a/microsite/releases.ts b/microsite/releases.ts new file mode 100644 index 0000000000..21e1451cec --- /dev/null +++ b/microsite/releases.ts @@ -0,0 +1,24 @@ +import fs from 'node:fs'; +import path from 'node:path'; + +const docsDir = path.resolve( + path.dirname(new URL(import.meta.url).pathname), + '../docs', +); + +export const releases = fs + .readdirSync(path.resolve(docsDir, 'releases')) + .filter(doc => doc.match(/^v\d+\.\d+\.\d+\.md$/)) + .map(doc => doc.replace(/\.md$/, '')) + .sort((a, b) => { + // Semver sort + const aVal = a + .slice(1) + .split('.') + .reduce((acc, val) => acc * 1000 + parseInt(val), 0); + const bVal = b + .slice(1) + .split('.') + .reduce((acc, val) => acc * 1000 + parseInt(val), 0); + return bVal - aVal; + }); diff --git a/microsite/sidebars.mjs b/microsite/sidebars.ts similarity index 96% rename from microsite/sidebars.mjs rename to microsite/sidebars.ts index 675f53a7d6..6b07952f2f 100644 --- a/microsite/sidebars.mjs +++ b/microsite/sidebars.ts @@ -1,21 +1,4 @@ -import fs from 'node:fs'; -import path from 'node:path'; - -const docsDir = path.resolve( - path.dirname(new URL(import.meta.url).pathname), - '../docs', -); - -const allReleaseDocs = fs.readdirSync(path.resolve(docsDir, 'releases')); -const mainRleases = allReleaseDocs - .filter(doc => doc.match(/^v\d+\.\d+\.\d+\.md$/)) - .map(doc => doc.replace(/\.md$/, '')) - .sort((a, b) => { // Semver sort - const aVal = a.slice(1).split('.').reduce((acc, val) => acc * 1000 + parseInt(val), 0); - const bVal = b.slice(1).split('.').reduce((acc, val) => acc * 1000 + parseInt(val), 0); - return bVal - aVal; - }) - .map(release => `releases/${release}`); +import { releases } from './releases'; export default { docs: { @@ -543,6 +526,6 @@ export default { References: ['references/glossary'], }, releases: { - 'Release Notes': mainRleases + 'Release Notes': releases.map(release => `releases/${release}`), }, }; diff --git a/microsite/tsconfig.json b/microsite/tsconfig.json index 71bc403643..9a5106747e 100644 --- a/microsite/tsconfig.json +++ b/microsite/tsconfig.json @@ -2,6 +2,7 @@ "extends": "@docusaurus/tsconfig", "compilerOptions": { "baseUrl": ".", + "allowJs": true, "types": [ "node", "@docusaurus/module-type-aliases", From 9c35b6b7ba4385507c3fa05d0eb197438790616d Mon Sep 17 00:00:00 2001 From: blam Date: Tue, 10 Sep 2024 15:46:03 +0200 Subject: [PATCH 3/6] chore: checkout docs from mainline Signed-off-by: blam --- .github/workflows/deploy_microsite.yml | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/.github/workflows/deploy_microsite.yml b/.github/workflows/deploy_microsite.yml index f07cf21784..0a52cac742 100644 --- a/.github/workflows/deploy_microsite.yml +++ b/.github/workflows/deploy_microsite.yml @@ -3,6 +3,7 @@ on: push: branches: - master + pull_request: permissions: contents: read @@ -184,6 +185,22 @@ jobs: name: stable-reference path: docs/reference + - name: debug before + run: | + ls docs + ls docs/releases + + - name: grab lastest releases docs + uses: actions/checkout@v4 + with: + clean: false + sparse-checkout: docs/releases + + - name: debug after + run: | + ls docs + ls docs/releases + - name: generate stable docs run: yarn docusaurus docs:version stable working-directory: microsite From 043972f32546cd2d985d79525608a0943c07ef72 Mon Sep 17 00:00:00 2001 From: blam Date: Tue, 10 Sep 2024 16:01:41 +0200 Subject: [PATCH 4/6] ichore: Finish Signed-off-by: blam --- .github/workflows/deploy_microsite.yml | 16 ++-------------- microsite/{lighthouserc.js => lighthouserc.ts} | 4 ++-- 2 files changed, 4 insertions(+), 16 deletions(-) rename microsite/{lighthouserc.js => lighthouserc.ts} (97%) diff --git a/.github/workflows/deploy_microsite.yml b/.github/workflows/deploy_microsite.yml index 0a52cac742..aa5d06e4ba 100644 --- a/.github/workflows/deploy_microsite.yml +++ b/.github/workflows/deploy_microsite.yml @@ -3,7 +3,6 @@ on: push: branches: - master - pull_request: permissions: contents: read @@ -185,21 +184,10 @@ jobs: name: stable-reference path: docs/reference - - name: debug before - run: | - ls docs - ls docs/releases - - name: grab lastest releases docs - uses: actions/checkout@v4 - with: - clean: false - sparse-checkout: docs/releases - - - name: debug after run: | - ls docs - ls docs/releases + git fetch origin master --depth 1 + git checkout FETCH_HEAD -- docs/releases - name: generate stable docs run: yarn docusaurus docs:version stable diff --git a/microsite/lighthouserc.js b/microsite/lighthouserc.ts similarity index 97% rename from microsite/lighthouserc.js rename to microsite/lighthouserc.ts index f0024ee0b3..5775bd19ee 100644 --- a/microsite/lighthouserc.js +++ b/microsite/lighthouserc.ts @@ -14,9 +14,9 @@ * limitations under the License. */ -var sidebars = require('./sidebars.json'); +import sidebars from './sidebars'; -module.exports = { +export default { ci: { collect: { url: [ From 28e2ca1ed8bc9b1a25f8fd2bd6da1d664719e9f5 Mon Sep 17 00:00:00 2001 From: blam Date: Tue, 10 Sep 2024 16:25:31 +0200 Subject: [PATCH 5/6] chore: converting things to js Signed-off-by: blam --- microsite/docusaurus.config.ts | 2 +- microsite/{lighthouserc.ts => lighthouserc.js} | 4 ++-- microsite/{releases.ts => releases.js} | 11 ++++------- microsite/{sidebars.ts => sidebars.js} | 4 ++-- 4 files changed, 9 insertions(+), 12 deletions(-) rename microsite/{lighthouserc.ts => lighthouserc.js} (97%) rename microsite/{releases.ts => releases.js} (70%) rename microsite/{sidebars.ts => sidebars.js} (99%) diff --git a/microsite/docusaurus.config.ts b/microsite/docusaurus.config.ts index 726a1fbf48..af96ef4c42 100644 --- a/microsite/docusaurus.config.ts +++ b/microsite/docusaurus.config.ts @@ -86,7 +86,7 @@ const config: Config = { docs: { editUrl: 'https://github.com/backstage/backstage/edit/master/docs/', path: '../docs', - sidebarPath: 'sidebars.ts', + sidebarPath: 'sidebars.js', ...(useVersionedDocs ? { includeCurrentVersion: true, diff --git a/microsite/lighthouserc.ts b/microsite/lighthouserc.js similarity index 97% rename from microsite/lighthouserc.ts rename to microsite/lighthouserc.js index 5775bd19ee..c75138d4c3 100644 --- a/microsite/lighthouserc.ts +++ b/microsite/lighthouserc.js @@ -14,9 +14,9 @@ * limitations under the License. */ -import sidebars from './sidebars'; +const sidebars = require('./sidebars'); -export default { +module.exports = { ci: { collect: { url: [ diff --git a/microsite/releases.ts b/microsite/releases.js similarity index 70% rename from microsite/releases.ts rename to microsite/releases.js index 21e1451cec..4136b0edad 100644 --- a/microsite/releases.ts +++ b/microsite/releases.js @@ -1,12 +1,9 @@ -import fs from 'node:fs'; -import path from 'node:path'; +const fs = require('fs'); +const path = require('path'); -const docsDir = path.resolve( - path.dirname(new URL(import.meta.url).pathname), - '../docs', -); +const docsDir = path.resolve(__dirname, '../docs'); -export const releases = fs +exports.releases = fs .readdirSync(path.resolve(docsDir, 'releases')) .filter(doc => doc.match(/^v\d+\.\d+\.\d+\.md$/)) .map(doc => doc.replace(/\.md$/, '')) diff --git a/microsite/sidebars.ts b/microsite/sidebars.js similarity index 99% rename from microsite/sidebars.ts rename to microsite/sidebars.js index 6b07952f2f..9525141073 100644 --- a/microsite/sidebars.ts +++ b/microsite/sidebars.js @@ -1,6 +1,6 @@ -import { releases } from './releases'; +const { releases } = require('./releases'); -export default { +module.exports = { docs: { Overview: [ 'overview/what-is-backstage', From 5509b5a8291546cc05f2dd1ece1c16cdec888e1f Mon Sep 17 00:00:00 2001 From: blam Date: Wed, 11 Sep 2024 12:13:33 +0200 Subject: [PATCH 6/6] chore: smol fix Signed-off-by: blam --- docs/architecture-decisions/index.md | 2 +- docs/contribute/project-structure.md | 2 +- docs/publishing.md | 2 +- microsite/README.md | 25 +++++++++++++------------ mkdocs.yml | 2 +- 5 files changed, 17 insertions(+), 16 deletions(-) diff --git a/docs/architecture-decisions/index.md b/docs/architecture-decisions/index.md index 615d737fe1..3432264453 100644 --- a/docs/architecture-decisions/index.md +++ b/docs/architecture-decisions/index.md @@ -27,7 +27,7 @@ Records should be stored under the `architecture-decisions` directory. - Address and integrate feedback from the community - Eventually, assign a number - Add the path of the ADR to the microsite sidebar in - [`sidebars.json`](https://github.com/backstage/backstage/blob/master/microsite/sidebars.json) + [`sidebars.js`](https://github.com/backstage/backstage/blob/master/microsite/sidebars.js) - Add the path of the ADR to the [`mkdocs.yml`](https://github.com/backstage/backstage/blob/master/mkdocs.yml) - Merge the pull request diff --git a/docs/contribute/project-structure.md b/docs/contribute/project-structure.md index f06fba0523..32a692e700 100644 --- a/docs/contribute/project-structure.md +++ b/docs/contribute/project-structure.md @@ -39,7 +39,7 @@ the code. - [`docs/`](https://github.com/backstage/backstage/tree/master/docs) - This is where we keep all of our documentation Markdown files. These end up on https://backstage.io/docs. Just keep in mind that changes to the - [`sidebars.json`](https://github.com/backstage/backstage/blob/master/microsite/sidebars.json) + [`sidebars.js`](https://github.com/backstage/backstage/blob/master/microsite/sidebars.js) file may be needed as sections are added/removed. - [`.editorconfig`](https://github.com/backstage/backstage/tree/master/.editorconfig) - diff --git a/docs/publishing.md b/docs/publishing.md index 50d78ebf09..740292949f 100644 --- a/docs/publishing.md +++ b/docs/publishing.md @@ -51,7 +51,7 @@ Additional steps for the main line release - Mention any security fixes - Create Release Notes PR - Add the release note file as [`/docs/releases/vx.y.0.md`](./releases) - - Add an entry to [`/microsite/sidebar.json`](https://github.com/backstage/backstage/blob/master/microsite/sidebars.json) for the release note + - Add an entry to [`/microsite/sidebar.js`](https://github.com/backstage/backstage/blob/master/microsite/sidebars.js) for the release note - Update the navigation bar item in [`/microsite/docusaurus.config.ts`](https://github.com/backstage/backstage/blob/master/microsite/docusaurus.config.ts) to point to the new release note - Finally copy the content, without the metadata header, into the description of the [`Version Packages` Pull Request](https://github.com/backstage/backstage/pulls?q=is%3Aopen+is%3Apr+in%3Atitle+%22Version+Packages) diff --git a/microsite/README.md b/microsite/README.md index 5bd20254b6..62a28fb6a3 100644 --- a/microsite/README.md +++ b/microsite/README.md @@ -61,7 +61,7 @@ my-docusaurus/ css/ img/ package.json - sidebars.json + sidebars.js siteConfig.js ``` @@ -116,19 +116,20 @@ For more information about blog posts, click [here](https://docusaurus.io/docs/e My new content here.. ``` -2. Refer to that doc's ID in an existing sidebar in `website/sidebars.json`: +2. Refer to that doc's ID in an existing sidebar in `website/sidebars.js`: - ```javascript + ```js // Add newly-created-doc to the Getting Started category of docs - { - "docs": { - "Getting Started": [ - "quick-start", - "newly-created-doc" // new doc here - ], - ... - }, - ... + module.exports = { + ... + docs: { + "Getting Started": [ + "quick-start", + "newly-created-doc" // new doc here + ], + ... + }, + ... } ``` diff --git a/mkdocs.yml b/mkdocs.yml index d907e580a8..b2d0a5489d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -6,7 +6,7 @@ edit_uri: edit/master/docs plugins: - techdocs-core -# For sidebar navigation on https://backstage.io/, see `microsite/sidebars.json` +# For sidebar navigation on https://backstage.io/, see `microsite/sidebars.js` nav: - Overview: - What is Backstage?: 'overview/what-is-backstage.md'