diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 46b11576eb..adf04c48e2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -381,7 +381,7 @@ Or from the Settings UI look for the "Git: Always Sign Off" setting and check th ## API Reports -Backstage uses [API Extractor](https://api-extractor.com/) and TSDoc comments to generate API Reports in Markdown format. These reports are what drive the [API Reference documentation](https://backstage.io/docs/reference/). What this means is that if you are making changes to the API or adding a new plugin then you will need either generate a new API Report or update an existing API Report. If you don't do this the CI build will fail when you create your Pull Request. +Backstage uses [API Extractor](https://api-extractor.com/) and TSDoc comments to generate API Reports in Markdown format. What this means is that if you are making changes to the API or adding a new plugin then you will need either generate a new API Report or update an existing API Report. If you don't do this the CI build will fail when you create your Pull Request. There are two ways you can do this: diff --git a/beps/0002-dynamic-frontend-plugins/README.md b/beps/0002-dynamic-frontend-plugins/README.md index 4787f0fb7a..c783cf052e 100644 --- a/beps/0002-dynamic-frontend-plugins/README.md +++ b/beps/0002-dynamic-frontend-plugins/README.md @@ -301,7 +301,7 @@ An example of [integration with scalprum](https://github.com/backstage/backstage **Dynamic Feature configuration** -The dynamic remote loading can be added directly into the [`createApp`](https://backstage.io/docs/reference/frontend-defaults.createapp) function. +The dynamic remote loading can be added directly into the [`createApp`](https://backstage.io/api/stable/functions/_backstage_frontend-defaults.createApp.html) function. The current `feature` type can be expanded with a `DynamicFrontendFeature` type: @@ -351,7 +351,7 @@ const scalprum = initialize({ }); ``` -Because the [`appLoader`](https://backstage.io/docs/reference/frontend-defaults.createapp) is already async, it is a perfect place to load the plugin registry and init the dynamic plugins. +Because the [`appLoader`](https://backstage.io/api/stable/functions/_backstage_frontend-defaults.createApp.html) is already async, it is a perfect place to load the plugin registry and init the dynamic plugins. Initializing the dynamic feature is just a case of mapping the `DynamicFrontendFeature` to `FrontendFeature` via Scalprum: diff --git a/docs/architecture-decisions/adr013-use-node-fetch.md b/docs/architecture-decisions/adr013-use-node-fetch.md index 664faed1db..2172754ac7 100644 --- a/docs/architecture-decisions/adr013-use-node-fetch.md +++ b/docs/architecture-decisions/adr013-use-node-fetch.md @@ -32,7 +32,7 @@ const users = await response.json(); ``` Frontend plugins and packages should prefer to use the -[`fetchApiRef`](https://backstage.io/docs/reference/core-plugin-api.fetchapiref). +[`fetchApiRef`](https://backstage.io/api/stable/variables/_backstage_core-plugin-api.index.fetchApiRef.html). It uses `cross-fetch` internally. Example: ```ts diff --git a/docs/architecture-decisions/adr014-use-fetch.md b/docs/architecture-decisions/adr014-use-fetch.md index 9faa6c9ead..363154fd8d 100644 --- a/docs/architecture-decisions/adr014-use-fetch.md +++ b/docs/architecture-decisions/adr014-use-fetch.md @@ -33,7 +33,7 @@ const users = await response.json(); ``` Frontend plugins and packages should prefer to use the -[`fetchApiRef`](https://backstage.io/docs/reference/core-plugin-api.fetchapiref). +[`fetchApiRef`](https://backstage.io/api/stable/variables/_backstage_core-plugin-api.index.fetchApiRef.html). ```ts import { useApi } from '@backstage/core-plugin-api'; diff --git a/docs/auth/identity-resolver.md b/docs/auth/identity-resolver.md index 5fb69c7955..0d4b50dcbe 100644 --- a/docs/auth/identity-resolver.md +++ b/docs/auth/identity-resolver.md @@ -287,7 +287,7 @@ async signInResolver(info, ctx) { If you throw an error in the sign in resolver function, the sign in attempt is immediately rejected, and the error details are presented in the user interface. -The `ctx` context [has several useful functions](https://backstage.io/docs/reference/plugin-auth-node.authresolvercontext/) +The `ctx` context [has several useful functions](https://backstage.io/api/stable/types/_backstage_plugin-auth-node.AuthResolverContext.html) for issuing tokens in various ways. ### Custom Ownership Resolution diff --git a/docs/auth/index.md b/docs/auth/index.md index 71d205cc01..fb85eb999b 100644 --- a/docs/auth/index.md +++ b/docs/auth/index.md @@ -287,7 +287,7 @@ sign-in resolvers so that they resolve to the same identity regardless of the me ## Scaffolder Configuration (Software Templates) -If you want to use the authentication capabilities of the [Repository Picker](../features/software-templates/writing-templates.md#the-repository-picker) inside your software templates, you will need to configure the [`ScmAuthApi`](https://backstage.io/docs/reference/integration-react.scmauthapi) alongside your authentication provider. It is an API used to authenticate towards different SCM systems in a generic way, based on what resource is being accessed. +If you want to use the authentication capabilities of the [Repository Picker](../features/software-templates/writing-templates.md#the-repository-picker) inside your software templates, you will need to configure the [`ScmAuthApi`](https://backstage.io/api/stable/interfaces/_backstage_integration-react.ScmAuthApi.html) alongside your authentication provider. It is an API used to authenticate towards different SCM systems in a generic way, based on what resource is being accessed. To set it up, you'll need to add an API factory entry to `packages/app/src/apis.ts`. The example below sets up the `ScmAuthApi` for an already configured GitLab authentication provider: @@ -363,7 +363,7 @@ The default `ScmAuthApi` provides integrations for `github`, `gitlab`, `azure` a ScmAuth.createDefaultApiFactory(); ``` -If you require only a subset of these integrations, then you will need a custom implementation of the [`ScmAuthApi`](https://backstage.io/docs/reference/integration-react.scmauthapi). It is an API used to authenticate different SCM systems generically, based on what resource is being accessed, and is used for example, by the Scaffolder (Software Templates) and Catalog Import plugins. +If you require only a subset of these integrations, then you will need a custom implementation of the [`ScmAuthApi`](https://backstage.io/api/stable/interfaces/_backstage_integration-react.ScmAuthApi.html). It is an API used to authenticate different SCM systems generically, based on what resource is being accessed, and is used for example, by the Scaffolder (Software Templates) and Catalog Import plugins. The first step is to remove the code that creates the default providers. diff --git a/docs/backend-system/building-backends/08-migrating.md b/docs/backend-system/building-backends/08-migrating.md index 3a6cf1baee..3aa06216b4 100644 --- a/docs/backend-system/building-backends/08-migrating.md +++ b/docs/backend-system/building-backends/08-migrating.md @@ -220,7 +220,7 @@ These are the deprecation messages for the most common replacements: - `getRootLogger` - This function will be removed in the future. If you need to get the root logger in the new system, please check out this documentation: https://backstage.io/docs/backend-system/core-services/logger - `getVoidLogger` - This function will be removed in the future. If you need to mock the root logger in the new system, please use `mockServices.logger.mock()` from `@backstage/backend-test-utils` instead. - `legacyPlugin` - Fully use the new backend system instead. -- `loadBackendConfig` - Please migrate to the new backend system and use `coreServices.rootConfig` instead, or the [@backstage/config-loader#ConfigSources](https://backstage.io/docs/reference/config-loader.configsources) facilities if required. +- `loadBackendConfig` - Please migrate to the new backend system and use `coreServices.rootConfig` instead, or the [@backstage/config-loader#ConfigSources](https://backstage.io/api/stable/classes/_backstage_config-loader.ConfigSources.html) facilities if required. - `loggerToWinstonLogger` - Migrate to use the new `LoggerService` instead. - `resolveSafeChildPath` - This function is deprecated and will be removed in a future release, see [#24493](https://github.com/backstage/backstage/issues/24493). Please use the `resolveSafeChildPath` function from the `@backstage/backend-plugin-api` package instead. - `ServerTokenManager` - Please [migrate](https://backstage.io/docs/tutorials/auth-service-migration) to the new `coreServices.auth`, `coreServices.httpAuth`, and `coreServices.userInfo` services as needed instead. diff --git a/docs/backend-system/building-plugins-and-modules/02-testing.md b/docs/backend-system/building-plugins-and-modules/02-testing.md index 67fb3d4f22..8aaead97af 100644 --- a/docs/backend-system/building-plugins-and-modules/02-testing.md +++ b/docs/backend-system/building-plugins-and-modules/02-testing.md @@ -57,7 +57,7 @@ interactions with the running test service. ### mock services -The [`mockServices`](https://backstage.io/docs/reference/backend-test-utils.mockservices) object from `@backstage/backend-test-utils` provides service factory functions, and mocks for all core services that you can use to verify interactions between plugin and services. +The [`mockServices`](https://backstage.io/api/stable/modules/_backstage_backend-test-utils.index.mockServices.html) object from `@backstage/backend-test-utils` provides service factory functions, and mocks for all core services that you can use to verify interactions between plugin and services. All mock services provide a factory function that is sufficient for most tests. Here's an example: @@ -106,24 +106,24 @@ describe('myPlugin', () => { Available services: -- [`auth`](https://backstage.io/docs/reference/backend-test-utils.mockservices.auth/) -- [`cache`](https://backstage.io/docs/reference/backend-test-utils.mockservices.cache/) -- [`database`](https://backstage.io/docs/reference/backend-test-utils.mockservices.database/) -- [`discovery`](https://backstage.io/docs/reference/backend-test-utils.mockservices.discovery/) -- [`events`](https://backstage.io/docs/reference/backend-test-utils.mockservices.events/) -- [`httpAuth`](https://backstage.io/docs/reference/backend-test-utils.mockservices.httpAuth/) -- [`httpRouter`](https://backstage.io/docs/reference/backend-test-utils.mockservices.httpRouter/) -- [`lifecycle`](https://backstage.io/docs/reference/backend-test-utils.mockservices.lifecycle/) -- [`logger`](https://backstage.io/docs/reference/backend-test-utils.mockservices.logger/) -- [`permissions`](https://backstage.io/docs/reference/backend-test-utils.mockservices.permissions/) -- [`rootConfig`](https://backstage.io/docs/reference/backend-test-utils.mockservices.rootConfig/) -- [`rootHealth`](https://backstage.io/docs/reference/backend-test-utils.mockservices.rootHealth/) -- [`rootHttpRouter`](https://backstage.io/docs/reference/backend-test-utils.mockservices.rootHttpRouter/) -- [`rootLifecycle`](https://backstage.io/docs/reference/backend-test-utils.mockservices.rootLifecycle/) -- [`rootLogger`](https://backstage.io/docs/reference/backend-test-utils.mockservices.rootLogger/) -- [`scheduler`](https://backstage.io/docs/reference/backend-test-utils.mockservices.scheduler/) -- [`urlReader`](https://backstage.io/docs/reference/backend-test-utils.mockservices.urlReader/) -- [`userInfo`](https://backstage.io/docs/reference/backend-test-utils.mockservices.userInfo/) +- [`auth`](https://backstage.io/api/stable/modules/_backstage_backend-test-utils.index.mockServices.html#auth) +- [`cache`](https://backstage.io/api/stable/modules/_backstage_backend-test-utils.index.mockServices.html#cache) +- [`database`](https://backstage.io/api/stable/modules/_backstage_backend-test-utils.index.mockServices.html#database) +- [`discovery`](https://backstage.io/api/stable/modules/_backstage_backend-test-utils.index.mockServices.html#discovery) +- [`events`](https://backstage.io/api/stable/modules/_backstage_backend-test-utils.index.mockServices.html#events) +- [`httpAuth`](https://backstage.io/api/stable/modules/_backstage_backend-test-utils.index.mockServices.html#httpAuth) +- [`httpRouter`](https://backstage.io/api/stable/modules/_backstage_backend-test-utils.index.mockServices.html#httpRouter) +- [`lifecycle`](https://backstage.io/api/stable/modules/_backstage_backend-test-utils.index.mockServices.html#lifecycle) +- [`logger`](https://backstage.io/api/stable/modules/_backstage_backend-test-utils.index.mockServices.html#logger) +- [`permissions`](https://backstage.io/api/stable/modules/_backstage_backend-test-utils.index.mockServices.html#permissions) +- [`rootConfig`](https://backstage.io/api/stable/modules/_backstage_backend-test-utils.index.mockServices.html#rootConfig) +- [`rootHealth`](https://backstage.io/api/stable/modules/_backstage_backend-test-utils.index.mockServices.html#rootHealth) +- [`rootHttpRouter`](https://backstage.io/api/stable/modules/_backstage_backend-test-utils.index.mockServices.html#rootHttpRouter) +- [`rootLifecycle`](https://backstage.io/api/stable/modules/_backstage_backend-test-utils.index.mockServices.html#rootLifecycle/) +- [`rootLogger`](https://backstage.io/api/stable/modules/_backstage_backend-test-utils.index.mockServices.html#rootLogger/) +- [`scheduler`](https://backstage.io/api/stable/modules/_backstage_backend-test-utils.index.mockServices.html#scheduler/) +- [`urlReader`](https://backstage.io/api/stable/modules/_backstage_backend-test-utils.index.mockServices.html#urlReader/) +- [`userInfo`](https://backstage.io/api/stable/modules/_backstage_backend-test-utils.index.mockServices.html#userInfo/) ## Testing Remote Service Interactions diff --git a/docs/features/kubernetes/configuration.md b/docs/features/kubernetes/configuration.md index 6a3f3760bf..922bfb6018 100644 --- a/docs/features/kubernetes/configuration.md +++ b/docs/features/kubernetes/configuration.md @@ -195,11 +195,11 @@ strategy. This method can be quite helpful when used in combination with an ingestion procedure like the -[`GkeEntityProvider`](https://backstage.io/docs/reference/plugin-catalog-backend-module-gcp.gkeentityprovider/) +[`GkeEntityProvider`](https://backstage.io/api/stable/classes/_backstage_plugin-catalog-backend-module-gcp.index.GkeEntityProvider.html) (installation documented [here](https://github.com/backstage/backstage/tree/master/plugins/catalog-backend-module-gcp#installation)) or the -[`AwsEKSClusterProcessor`](https://backstage.io/docs/reference/plugin-catalog-backend-module-aws.awseksclusterprocessor/) +[`AwsEKSClusterProcessor`](https://backstage.io/api/stable/classes/_backstage_plugin-catalog-backend-module-aws.index.AwsEKSClusterProcessor.html) to automatically update the set of clusters tracked by Backstage. For this method to work any entity that would be using this `Resource` to help drive the Kubernetes details in the Catalog's Entity pages needs to have a `dependsOn` relationship setup. Here's a quick example: diff --git a/docs/features/kubernetes/installation.md b/docs/features/kubernetes/installation.md index fa37253cd6..0268a9b046 100644 --- a/docs/features/kubernetes/installation.md +++ b/docs/features/kubernetes/installation.md @@ -75,7 +75,7 @@ Backstage app. If either existing [cluster locators](https://backstage.io/docs/features/kubernetes/configuration#clusterlocatormethods) don't work for your use-case, it is possible to implement a custom -[KubernetesClustersSupplier](https://backstage.io/docs/reference/plugin-kubernetes-backend.kubernetesclusterssupplier). +[KubernetesClustersSupplier](https://backstage.io/api/stable/interfaces/_backstage_plugin-kubernetes-node.KubernetesClustersSupplier.html). Here's a very simplified example: diff --git a/docs/features/search/collators.md b/docs/features/search/collators.md index f2ad982812..37cb59559a 100644 --- a/docs/features/search/collators.md +++ b/docs/features/search/collators.md @@ -86,7 +86,7 @@ Now with this example it will collate all entities that are `kind` equal to `api :::tip -The filter configuration is implemented using the `EntityFilterQuery` syntax. The [reference documentation on `EntityFilterQuery`](https://backstage.io/docs/reference/catalog-client.entityfilterquery/) provides more details. +The filter configuration is implemented using the `EntityFilterQuery` syntax. The [reference documentation on `EntityFilterQuery`](https://backstage.io/api/stable/types/_backstage_catalog-client.index.EntityFilterQuery.html) provides more details. ::: diff --git a/docs/features/search/how-to-guides.md b/docs/features/search/how-to-guides.md index f0823ac47e..018c70479d 100644 --- a/docs/features/search/how-to-guides.md +++ b/docs/features/search/how-to-guides.md @@ -232,7 +232,7 @@ Remember to export your new extension via your plugin's `index.ts` so that it is export { YourSearchResultListItem } from './plugin.ts'; ``` -For more details, see the [createSearchResultListItemExtension](https://backstage.io/docs/reference/plugin-search-react.createsearchresultlistitemextension) API reference. +For more details, see the [createSearchResultListItemExtension](https://backstage.io/api/stable/functions/_backstage_plugin-search-react.index.createSearchResultListItemExtension.html) API reference. ### 2. Custom search result extension in the SearchPage diff --git a/docs/features/software-catalog/api.md b/docs/features/software-catalog/api.md index 96420cd37e..ca8b8f638d 100644 --- a/docs/features/software-catalog/api.md +++ b/docs/features/software-catalog/api.md @@ -27,7 +27,7 @@ one organization to the other, especially in production, but is commonly your Some or all of the endpoints may accept or require an `Authorization` header with a `Bearer` token, which should then be the Backstage token returned by the -[`identity API`](https://backstage.io/docs/reference/core-plugin-api.identityapiref). +[`identity API`](https://backstage.io/api/stable/variables/_backstage_core-plugin-api.index.identityApiRef.html). ## Entities diff --git a/docs/features/software-catalog/references.md b/docs/features/software-catalog/references.md index 9a5a037d6d..16ab90b6e0 100644 --- a/docs/features/software-catalog/references.md +++ b/docs/features/software-catalog/references.md @@ -40,7 +40,7 @@ used, and the relevant documentation should specify which rule applies where. Entity ref strings are frequently passed between systems as identifiers of entities. In those cases the refs should always be complete (have all three parts). The sender should ensure that the refs are always lowercased in an -`en-US` locale, preferably by using [the `stringifyEntityRef` function](https://backstage.io/docs/reference/catalog-model.stringifyentityref/) +`en-US` locale, preferably by using [the `stringifyEntityRef` function](https://backstage.io/api/stable/functions/_backstage_catalog-model.index.stringifyEntityRef.html) which does this automatically. The receiver should treat incoming refs case insensitively to avoid problems with senders who do not obey this rule. diff --git a/docs/features/software-templates/templating-extensions.md b/docs/features/software-templates/templating-extensions.md index 242966ae5f..b131f51bc9 100644 --- a/docs/features/software-templates/templating-extensions.md +++ b/docs/features/software-templates/templating-extensions.md @@ -517,8 +517,8 @@ specifying options to the scaffolder backend plugin's `createRouter` function [nunjucks]: https://mozilla.github.io/nunjucks [filter]: https://mozilla.github.io/nunjucks/templating.html#filters [global-fn]: https://mozilla.github.io/nunjucks/templating.html#global-functions -[parseRepoUrl]: https://backstage.io/docs/reference/plugin-scaffolder-node.parserepourl -[CompoundEntityRef]: https://backstage.io/docs/reference/catalog-model.compoundentityref +[parseRepoUrl]: https://backstage.io/api/stable/functions/_backstage_plugin-scaffolder-node.index.parseRepoUrl.html +[CompoundEntityRef]: https://backstage.io/api/stable/types/_backstage_catalog-model.index.CompoundEntityRef.html [Zod]: https://zod.dev/ [zod-fn]: https://zod.dev/?id=functions [piped]: https://en.wikipedia.org/wiki/Pipeline_(Unix)#Pipelines_in_command_line_interfaces diff --git a/docs/features/software-templates/writing-custom-field-extensions.md b/docs/features/software-templates/writing-custom-field-extensions.md index 477fa66e5b..3fe4d82a1f 100644 --- a/docs/features/software-templates/writing-custom-field-extensions.md +++ b/docs/features/software-templates/writing-custom-field-extensions.md @@ -22,7 +22,7 @@ Field extensions are a way to combine an ID, a `React` Component and a the `Scaffolder` frontend plugin in your own `App.tsx`. You can create your own Field Extension by using the -[`createScaffolderFieldExtension`](https://backstage.io/docs/reference/plugin-scaffolder.createscaffolderfieldextension) +[`createScaffolderFieldExtension`](https://backstage.io/api/stable/variables/_backstage_plugin-scaffolder.index.createScaffolderFieldExtension.html) `API` like below. As an example, we will create a component that validates whether a string is in the `Kebab-case` pattern: @@ -151,7 +151,7 @@ const routes = ( ### Async Validation Function -A validation function can be asynchronous and use [Utility APIs](https://backstage.io/docs/api/utility-apis/) via the `ApiHolder` in the [field validation context](https://backstage.io/docs/reference/plugin-scaffolder-react.customfieldvalidator). The example below uses the `catalogApiRef` to check if the submitted value (in this scenario an entity ref) exists in the catalog. +A validation function can be asynchronous and use [Utility APIs](https://backstage.io/docs/api/utility-apis/) via the `ApiHolder` in the [field validation context](https://backstage.io/api/stable/types/_backstage_plugin-scaffolder-react.index.CustomFieldValidator.html). The example below uses the `catalogApiRef` to check if the submitted value (in this scenario an entity ref) exists in the catalog. ```tsx import { FieldValidation } from '@rjsf/utils'; diff --git a/docs/features/software-templates/writing-custom-step-layouts.md b/docs/features/software-templates/writing-custom-step-layouts.md index f2ed5eb96d..ad766270f2 100644 --- a/docs/features/software-templates/writing-custom-step-layouts.md +++ b/docs/features/software-templates/writing-custom-step-layouts.md @@ -16,7 +16,7 @@ This is the same [field](https://rjsf-team.github.io/react-jsonschema-form/docs/ ## Registering a React component as a custom step layout -The [createScaffolderLayout](https://backstage.io/docs/reference/plugin-scaffolder-react.createscaffolderlayout) function is used to mark a component as a custom step layout: +The [createScaffolderLayout](https://backstage.io/api/stable/functions/_backstage_plugin-scaffolder-react.index.createScaffolderLayout.html) function is used to mark a component as a custom step layout: ```tsx import { scaffolderPlugin } from '@backstage/plugin-scaffolder'; diff --git a/docs/features/techdocs/addons--new.md b/docs/features/techdocs/addons--new.md index 8c58eb892c..cbafcbe127 100644 --- a/docs/features/techdocs/addons--new.md +++ b/docs/features/techdocs/addons--new.md @@ -89,12 +89,12 @@ page header, TechDocs Addons whose location is `Header` will not be rendered. Addons can, in principle, be provided by any plugin! To make it easier to discover available Addons, we've compiled a list of them here: -| Addon | Package/Plugin | Description | -| ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`techDocsExpandableNavigationAddonModule`](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.expandablenavigation) | `@backstage/plugin-techdocs-module-addons-contrib/alpha` | Allows TechDocs users to expand or collapse the entire TechDocs main navigation, and keeps the user's preferred state between documentation sites. | -| [`techDocsReportIssueAddonModule`](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.reportissue) | `@backstage/plugin-techdocs-module-addons-contrib/alpha` | Allows TechDocs users to select a portion of text on a TechDocs page and open an issue against the repository that contains the documentation, populating the issue description with the selected text according to a configurable template. | -| [`techDocsTextSizeAddonModule`](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.textsize) | `@backstage/plugin-techdocs-module-addons-contrib/alpha` | This TechDocs addon allows users to customize text size on documentation pages, they can select how much they want to increase or decrease the font size via slider or buttons. The default value for font size is 100% and this setting is kept in the browser's local storage whenever it is changed. | -| [`techDocsLightBoxAddonModule`](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.lightbox) | `@backstage/plugin-techdocs-module-addons-contrib/alpha` | This TechDocs addon allows users to open images in a light-box on documentation pages, they can navigate between images if there are several on one page. The image size of the light-box image is the same as the image size on the document page. When clicking on the zoom icon it zooms the image to fit in the screen (similar to `background-size: contain`). | +| Addon | Package/Plugin | Description | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`techDocsExpandableNavigationAddonModule`](https://backstage.io/api/stable/variables/_backstage_plugin-techdocs-module-addons-contrib.plugins_techdocs-module-addons-contrib_src_alpha.techDocsExpandableNavigationAddonModule.html) | `@backstage/plugin-techdocs-module-addons-contrib/alpha` | Allows TechDocs users to expand or collapse the entire TechDocs main navigation, and keeps the user's preferred state between documentation sites. | +| [`techDocsReportIssueAddonModule`](https://backstage.io/api/stable/variables/_backstage_plugin-techdocs-module-addons-contrib.plugins_techdocs-module-addons-contrib_src_alpha.techDocsReportIssueAddonModule.html) | `@backstage/plugin-techdocs-module-addons-contrib/alpha` | Allows TechDocs users to select a portion of text on a TechDocs page and open an issue against the repository that contains the documentation, populating the issue description with the selected text according to a configurable template. | +| [`techDocsTextSizeAddonModule`](https://backstage.io/api/stable/variables/_backstage_plugin-techdocs-module-addons-contrib.plugins_techdocs-module-addons-contrib_src_alpha.techDocsReportIssueAddonModule.html) | `@backstage/plugin-techdocs-module-addons-contrib/alpha` | This TechDocs addon allows users to customize text size on documentation pages, they can select how much they want to increase or decrease the font size via slider or buttons. The default value for font size is 100% and this setting is kept in the browser's local storage whenever it is changed. | +| [`techDocsLightBoxAddonModule`](https://backstage.io/api/stable/variables/_backstage_plugin-techdocs-module-addons-contrib.plugins_techdocs-module-addons-contrib_src_alpha.techDocsLightBoxAddonModule.html) | `@backstage/plugin-techdocs-module-addons-contrib/alpha` | This TechDocs addon allows users to open images in a light-box on documentation pages, they can navigate between images if there are several on one page. The image size of the light-box image is the same as the image size on the document page. When clicking on the zoom icon it zooms the image to fit in the screen (similar to `background-size: contain`). | Got an Addon to contribute? Feel free to add a row above! diff --git a/docs/features/techdocs/addons.md b/docs/features/techdocs/addons.md index 435239794b..78b472edf2 100644 --- a/docs/features/techdocs/addons.md +++ b/docs/features/techdocs/addons.md @@ -126,12 +126,12 @@ page header, TechDocs Addons whose location is `Header` will not be rendered. Addons can, in principle, be provided by any plugin! To make it easier to discover available Addons, we've compiled a list of them here: -| Addon | Package/Plugin | Description | -| ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [``](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.expandablenavigation) | `@backstage/plugin-techdocs-module-addons-contrib` | Allows TechDocs users to expand or collapse the entire TechDocs main navigation, and keeps the user's preferred state between documentation sites. | -| [``](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.reportissue) | `@backstage/plugin-techdocs-module-addons-contrib` | Allows TechDocs users to select a portion of text on a TechDocs page and open an issue against the repository that contains the documentation, populating the issue description with the selected text according to a configurable template. | -| [``](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.textsize) | `@backstage/plugin-techdocs-module-addons-contrib` | This TechDocs addon allows users to customize text size on documentation pages, they can select how much they want to increase or decrease the font size via slider or buttons. The default value for font size is 100% and this setting is kept in the browser's local storage whenever it is changed. | -| [``](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.lightbox) | `@backstage/plugin-techdocs-module-addons-contrib` | This TechDocs addon allows users to open images in a light-box on documentation pages, they can navigate between images if there are several on one page. The image size of the light-box image is the same as the image size on the document page. When clicking on the zoom icon it zooms the image to fit in the screen (similar to `background-size: contain`). | +| Addon | Package/Plugin | Description | +| -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [``](https://backstage.io/api/stable/variables/_backstage_plugin-techdocs-module-addons-contrib.index.ExpandableNavigation.html) | `@backstage/plugin-techdocs-module-addons-contrib` | Allows TechDocs users to expand or collapse the entire TechDocs main navigation, and keeps the user's preferred state between documentation sites. | +| [``](https://backstage.io/api/stable/variables/_backstage_plugin-techdocs-module-addons-contrib.index.ReportIssue.html) | `@backstage/plugin-techdocs-module-addons-contrib` | Allows TechDocs users to select a portion of text on a TechDocs page and open an issue against the repository that contains the documentation, populating the issue description with the selected text according to a configurable template. | +| [``](https://backstage.io/api/stable/variables/_backstage_plugin-techdocs-module-addons-contrib.index.TextSize.html) | `@backstage/plugin-techdocs-module-addons-contrib` | This TechDocs addon allows users to customize text size on documentation pages, they can select how much they want to increase or decrease the font size via slider or buttons. The default value for font size is 100% and this setting is kept in the browser's local storage whenever it is changed. | +| [``](https://backstage.io/api/stable/variables/_backstage_plugin-techdocs-module-addons-contrib.index.LightBox.html) | `@backstage/plugin-techdocs-module-addons-contrib` | This TechDocs addon allows users to open images in a light-box on documentation pages, they can navigate between images if there are several on one page. The image size of the light-box image is the same as the image size on the document page. When clicking on the zoom icon it zooms the image to fit in the screen (similar to `background-size: contain`). | Got an Addon to contribute? Feel free to add a row above! diff --git a/docs/features/techdocs/extensions.md b/docs/features/techdocs/extensions.md index 6c69d076a4..76cc571a0f 100644 --- a/docs/features/techdocs/extensions.md +++ b/docs/features/techdocs/extensions.md @@ -10,15 +10,15 @@ description: How to use the built-in TechDocs extension points The TechDocs backend plugin provides the following extension points: - `techdocsPreparerExtensionPoint` - - Register a custom docs [PreparerBase extension](https://backstage.io/docs/reference/plugin-techdocs-node.preparerbase/) + - Register a custom docs [PreparerBase extension](https://backstage.io/api/stable/types/_backstage_plugin-techdocs-node.PreparerBase.html) - Ideal for when you want a custom type of docs created for a specific entity type - `techdocsBuildsExtensionPoint` - Allows overriding the build phase Winston log transport (by default does not log to console) - - Allows overriding the [DocsBuildStrategy](https://backstage.io/docs/reference/plugin-techdocs-node.docsbuildstrategy/) + - Allows overriding the [DocsBuildStrategy](https://backstage.io/api/stable/interfaces/_backstage_plugin-techdocs-node.DocsBuildStrategy.html) - `techdocsPublisherExtensionPoint` - Register a custom docs publisher - `techdocsGeneratorExtensionPoint` - - Register a custom [TechdocsGenerator](https://backstage.io/docs/reference/plugin-techdocs-node.techdocsgenerator/) + - Register a custom [TechdocsGenerator](https://backstage.io/api/stable/classes/_backstage_plugin-techdocs-node.TechdocsGenerator.html) Extension points are exported from `@backstage/plugin-techdocs-backend`. diff --git a/docs/frontend-system/building-apps/01-index.md b/docs/frontend-system/building-apps/01-index.md index ed84aeafb2..8610dfb7b5 100644 --- a/docs/frontend-system/building-apps/01-index.md +++ b/docs/frontend-system/building-apps/01-index.md @@ -103,7 +103,7 @@ You can also pass overrides to the features array, for more details, please read ### Using an async features loader -In case you need to perform asynchronous operations before passing features to the `createApp` function, define a [feature loader](https://backstage.io/docs/reference/frontend-defaults.createappfeatureloader/) object and pass it to the `features` option: +In case you need to perform asynchronous operations before passing features to the `createApp` function, define a [feature loader](https://backstage.io/api/stable/functions/_backstage_frontend-plugin-api.index.createFrontendFeatureLoader.html) object and pass it to the `features` option: ```tsx title="packages/app/src/App.tsx" import { createApp } from '@backstage/frontend-defaults'; diff --git a/docs/frontend-system/building-apps/03-built-in-extensions.md b/docs/frontend-system/building-apps/03-built-in-extensions.md index 44316bd898..e1d0b0282d 100644 --- a/docs/frontend-system/building-apps/03-built-in-extensions.md +++ b/docs/frontend-system/building-apps/03-built-in-extensions.md @@ -18,7 +18,7 @@ extensions: ``` :::warning -Be careful when disabling built-in extensions, as there may be other extensions depending on their existence. For example, the built-in "alert display" extension displays messages retrieved via [AlertApi](https://backstage.io/docs/reference/core-plugin-api.alertapi) and disabling this extension will cause the application to no longer display these messages unless you install another extension that displays messages from `AlertApi`. +Be careful when disabling built-in extensions, as there may be other extensions depending on their existence. For example, the built-in "alert display" extension displays messages retrieved via [AlertApi](https://backstage.io/api/stable/types/_backstage_core-plugin-api.index.AlertApi.html) and disabling this extension will cause the application to no longer display these messages unless you install another extension that displays messages from `AlertApi`. ::: ## Override built-in extensions @@ -107,7 +107,7 @@ This is the extension that creates the app root element, so it renders root leve ##### Alert Display -An app root element extension that displays messages posted via the [`AlertApi`](https://backstage.io/docs/reference/core-plugin-api.alertapi). +An app root element extension that displays messages posted via the [`AlertApi`](https://backstage.io/api/stable/types/_backstage_core-plugin-api.index.AlertApi.html). | kind | namespace | name | id | | :--------------: | :-------: | :-----------: | :----------------------------------: | @@ -125,12 +125,12 @@ An app root element extension that displays messages posted via the [`AlertApi`] If you do not want to display alerts, disable this extension or if the available settings do not meet your needs, override this extension. :::warning -The built-in "alert display" extension displays messages retrieved via [AlertApi](https://backstage.io/docs/reference/core-plugin-api.alertapi) and disabling this extension will cause the application to no longer display these messages unless you install another extension that displays messages from `AlertApi`. +The built-in "alert display" extension displays messages retrieved via [AlertApi](https://backstage.io/api/stable/types/_backstage_core-plugin-api.index.AlertApi.html) and disabling this extension will cause the application to no longer display these messages unless you install another extension that displays messages from `AlertApi`. ::: ##### OAuth Request Dialog -An app root element extension that renders the oauth request dialog, it is based on the [oauthRequestApi](https://backstage.io/docs/reference/core-plugin-api.oauthrequestapi/). +An app root element extension that renders the oauth request dialog, it is based on the [oauthRequestApi](https://backstage.io/api/stable/types/_backstage_core-plugin-api.index.OAuthRequestApi.html). | kind | namespace | name | id | | :--------------: | :-------: | :------------------: | :-----------------------------------------: | @@ -146,10 +146,10 @@ Renders the app's sidebar and content in a specific layout. #### Inputs -| Name | Description | Type | Optional | Default | Extension creator | -| ------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -------- | ------- | ------------------------------------ | -| nav | A React element that renders the app sidebar. | [coreExtensionData.reactElement](https://backstage.io/docs/reference/frontend-plugin-api.coreextensiondata) | false | - | Override the `App/Nav` extension. | -| content | A React element that renders the app content. | [coreExtensionData.reactElement](https://backstage.io/docs/reference/frontend-plugin-api.coreextensiondata) | false | - | Override the `App/Routes` extension. | +| Name | Description | Type | Optional | Default | Extension creator | +| ------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ------------------------------------ | +| nav | A React element that renders the app sidebar. | [coreExtensionData.reactElement](https://backstage.io/api/stable/variables/_backstage_frontend-plugin-api.index.coreExtensionData.html) | false | - | Override the `App/Nav` extension. | +| content | A React element that renders the app content. | [coreExtensionData.reactElement](https://backstage.io/api/stable/variables/_backstage_frontend-plugin-api.index.coreExtensionData.html) | false | - | Override the `App/Routes` extension. | ### App nav @@ -161,10 +161,10 @@ Extension responsible for rendering the logo and items in the app's sidebar. #### Inputs -| Name | Description | Type | Optional | Default | Extension creator | -| ------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------- | -------------------------------------------------------------------------------------------------------- | -| content | Overrides the default content of the navbar. | [NavContentBlueprint.dataRefs.component](https://backstage.io/docs/reference/frontend-plugin-api.navcontentblueprint) | true | - | [NavContentBlueprint](https://backstage.io/docs/reference/frontend-plugin-api.navcontentblueprint) | -| items | Nav items target objects. | [createNavItemExtension.targetDataRef](https://backstage.io/docs/reference/frontend-plugin-api.createnavitemextension.targetdataref) | true | - | [createNavItemExtension](https://backstage.io/docs/reference/frontend-plugin-api.createnavitemextension) | +| Name | Description | Type | Optional | Default | Extension creator | +| ------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------- | +| content | Overrides the default content of the navbar. | [NavContentBlueprint.dataRefs.component](https://backstage.io/api/stable/variables/_backstage_plugin-app-react.NavContentBlueprint.html) | true | - | [NavContentBlueprint](https://backstage.io/api/stable/variables/_backstage_plugin-app-react.NavContentBlueprint.html) | +| items | Nav items target objects. | [createNavItemExtension.targetDataRef](https://backstage.io/docs/reference/frontend-plugin-api.createnavitemextension.targetdataref) | true | - | [createNavItemExtension](https://backstage.io/docs/reference/frontend-plugin-api.createnavitemextension) | ### App routes diff --git a/docs/integrations/github/discovery.md b/docs/integrations/github/discovery.md index e17f514058..66fdaa503b 100644 --- a/docs/integrations/github/discovery.md +++ b/docs/integrations/github/discovery.md @@ -375,7 +375,7 @@ schedule: timeout: { minutes: 3 } ``` -More information about scheduling can be found on the [SchedulerServiceTaskScheduleDefinition](https://backstage.io/docs/reference/backend-plugin-api.schedulerservicetaskscheduledefinition) page. +More information about scheduling can be found on the [SchedulerServiceTaskScheduleDefinition](https://backstage.io/api/stable/interfaces/_backstage_backend-plugin-api.index.SchedulerServiceTaskScheduleDefinition.html) page. Alternatively, or additionally, you can configure [github-apps](github-apps.md) authentication which carries a much higher rate limit at GitHub. diff --git a/docs/integrations/github/org.md b/docs/integrations/github/org.md index 2dac8b8866..5321423432 100644 --- a/docs/integrations/github/org.md +++ b/docs/integrations/github/org.md @@ -98,7 +98,7 @@ Directly under the `githubOrg` is a list of configurations, each entry is a stru - `id`: A stable id for this provider. Entities from this provider will be associated with this ID, so you should take care not to change it over time since that may lead to orphaned entities and/or conflicts. - `githubUrl`: The target that this provider should consume - `orgs` (optional): The list of the GitHub orgs to consume. If you only list a single org the generated group entities will use the `default` namespace, otherwise they will use the org name as the namespace. By default the provider will consume all accessible orgs on the given GitHub instance (support for GitHub App integration only). -- `schedule`: The refresh schedule to use, matches the structure of [`SchedulerServiceTaskScheduleDefinitionConfig`](https://backstage.io/docs/reference/backend-plugin-api.schedulerservicetaskscheduledefinitionconfig/) +- `schedule`: The refresh schedule to use, matches the structure of [`SchedulerServiceTaskScheduleDefinitionConfig`](https://backstage.io/api/stable/interfaces/_backstage_backend-plugin-api.index.SchedulerServiceTaskScheduleDefinition.html) - `pageSizes` (optional): Configure page sizes for GitHub GraphQL API queries to prevent `RESOURCE_LIMITS_EXCEEDED` errors. You can configure the following page sizes: - `teams`: Number of teams to fetch per page when querying organization teams (default: 25) diff --git a/docs/landing-page/doc-landing-page.md b/docs/landing-page/doc-landing-page.md index cb1b889851..8697144bd8 100644 --- a/docs/landing-page/doc-landing-page.md +++ b/docs/landing-page/doc-landing-page.md @@ -94,7 +94,7 @@ description: Documentation landing page.
  • Architecture Decision Records (ADRs)
  • Deprecations
  • Utility APIs
    • -
  • Package Index
    • +
  • API References
  • FAQ
    • diff --git a/docs/notifications/usage.md b/docs/notifications/usage.md index 94de585d21..7437ae1cce 100644 --- a/docs/notifications/usage.md +++ b/docs/notifications/usage.md @@ -22,7 +22,7 @@ All parametrization is done through component properties, such as the `Notificat ![Notifications Page](notificationsPage.png) -In the `packages/app/src/components/Root/Root.tsx`, tweak the [properties](https://backstage.io/docs/reference/plugin-notifications.notificationssidebaritem) of the `` per specific needs. +In the `packages/app/src/components/Root/Root.tsx`, tweak the [properties](https://backstage.io/api/stable/functions/_backstage_plugin-notifications.index.NotificationsSidebarItem.html) of the `` per specific needs. ## Usage diff --git a/docs/permissions/plugin-authors/04-authorizing-access-to-paginated-data.md b/docs/permissions/plugin-authors/04-authorizing-access-to-paginated-data.md index b81382ee16..9b79cec042 100644 --- a/docs/permissions/plugin-authors/04-authorizing-access-to-paginated-data.md +++ b/docs/permissions/plugin-authors/04-authorizing-access-to-paginated-data.md @@ -43,7 +43,7 @@ To avoid this situation, the permissions framework has support for filtering ite :::note Note -In order to perform authorization filtering in this way, the data source must allow filters to be logically combined with AND, OR, and NOT operators. The conditional decisions returned by the permissions framework use a [nested object](https://backstage.io/docs/reference/plugin-permission-common.permissioncriteria) to combine conditions. If you're implementing a filter API from scratch, we recommend using the same shape for ease of interoperability. If not, you'll need to implement a function which transforms the nested object into your own format. +In order to perform authorization filtering in this way, the data source must allow filters to be logically combined with AND, OR, and NOT operators. The conditional decisions returned by the permissions framework use a [nested object](https://backstage.io/api/stable/types/_backstage_plugin-permission-common.PermissionCriteria.html) to combine conditions. If you're implementing a filter API from scratch, we recommend using the same shape for ease of interoperability. If not, you'll need to implement a function which transforms the nested object into your own format. ::: diff --git a/docs/permissions/plugin-authors/05-frontend-authorization.md b/docs/permissions/plugin-authors/05-frontend-authorization.md index 4d673e3b4f..5aadae1d23 100644 --- a/docs/permissions/plugin-authors/05-frontend-authorization.md +++ b/docs/permissions/plugin-authors/05-frontend-authorization.md @@ -79,7 +79,7 @@ function AddTodo({ onAdd }: { onAdd: (title: string) => any }) { } ``` -Here we are using the [`usePermission` hook](https://backstage.io/docs/reference/plugin-permission-react.usepermission) to communicate with the permission policy and receive a decision on whether this user is authorized to create a todo list item. +Here we are using the [`usePermission` hook](https://backstage.io/api/stable/functions/_backstage_plugin-permission-react.usePermission.html) to communicate with the permission policy and receive a decision on whether this user is authorized to create a todo list item. It's really that simple! Let's change our policy to test the disabled button: @@ -98,7 +98,7 @@ And now you should see that you are not able to create a todo item from the fron ## Using `RequirePermission` -Providing a disabled state can be a helpful signal to users, but there may be cases where hiding the element is preferred. For such cases, you can use the provided [`RequirePermission` component](https://backstage.io/docs/reference/plugin-permission-react.requirepermission): +Providing a disabled state can be a helpful signal to users, but there may be cases where hiding the element is preferred. For such cases, you can use the provided [`RequirePermission` component](https://backstage.io/api/stable/functions/_backstage_plugin-permission-react.RequirePermission.html): ```tsx title="plugins/todo-list/src/components/TodoListPage/TodoListPage.tsx" import { diff --git a/docs/permissions/writing-a-policy.md b/docs/permissions/writing-a-policy.md index 576afcac21..d3bdc30330 100644 --- a/docs/permissions/writing-a-policy.md +++ b/docs/permissions/writing-a-policy.md @@ -66,9 +66,9 @@ Now with this policy in place the ability to delete entities in the Catalog is n ## What's in a policy? -Let's break this down a bit further. The request object of type [PolicyQuery](https://backstage.io/docs/reference/plugin-permission-node.policyquery) is a simple wrapper around [the Permission object](https://backstage.io/docs/reference/plugin-permission-common.permission). This permission object encapsulates information about the action that the user is attempting to perform (See [the Concepts page](./concepts.md) for more details). +Let's break this down a bit further. The request object of type [PolicyQuery](https://backstage.io/api/stable/types/_backstage_plugin-permission-node.index.PolicyQuery.html) is a simple wrapper around [the Permission object](https://backstage.io/api/stable/types/_backstage_plugin-permission-common.Permission.html). This permission object encapsulates information about the action that the user is attempting to perform (See [the Concepts page](./concepts.md) for more details). -In the policy above, we are checking to see if the provided action is a catalog entity delete action, which is the permission that the catalog plugin authors have created to represent the action of unregistering a catalog entity. If this is the case, we return a [Definitive Policy Decision](https://backstage.io/docs/reference/plugin-permission-common.definitivepolicydecision) of DENY. In all other cases, we return ALLOW (resulting in an allow-by-default behavior). +In the policy above, we are checking to see if the provided action is a catalog entity delete action, which is the permission that the catalog plugin authors have created to represent the action of unregistering a catalog entity. If this is the case, we return a [Definitive Policy Decision](https://backstage.io/api/stable/types/_backstage_plugin-permission-common.DefinitivePolicyDecision.html) of DENY. In all other cases, we return ALLOW (resulting in an allow-by-default behavior). As we confirmed in the previous section, we know that this now prevents us from unregistering catalog components. Hooray! But you may notice that this prevents _anyone_ from unregistering a component, which is not a very realistic policy. Let's improve this policy by disabling the unregister action _unless you are the owner of this component_. @@ -134,9 +134,9 @@ class CustomPermissionPolicy implements PermissionPolicy { Let's walk through the new code that we just added. -Instead of returning an Definitive Policy Decision, we use factory methods to construct a [Conditional Policy Decision](https://backstage.io/docs/reference/plugin-permission-common.conditionalpolicydecision) (See the [Concepts page](./concepts.md) for more details). Since the policy doesn't have enough information to determine if `user` is the entity owner, this criteria is encapsulated within the conditional decision. However, `createCatalogConditionalDecision` will not compile unless `request.permission` is a catalog entity [`ResourcePermission`](https://backstage.io/docs/reference/plugin-permission-common.resourcepermission). This type constraint ensures that policies return conditional decisions that are compatible with the requested permission. To address this, we use [`isPermission`](https://backstage.io/docs/reference/plugin-permission-common.ispermission) to ["narrow"](https://www.typescriptlang.org/docs/handbook/2/narrowing.html) the type of `request.permission` to `ResourcePermission<'catalog-entity'>`. This matches the runtime behavior that was in place before, but you'll notice that the type of `request.permission` has changed within the scope of that `if` statement. +Instead of returning an Definitive Policy Decision, we use factory methods to construct a [Conditional Policy Decision](https://backstage.io/api/stable/types/_backstage_plugin-permission-common.ConditionalPolicyDecision.html) (See the [Concepts page](./concepts.md) for more details). Since the policy doesn't have enough information to determine if `user` is the entity owner, this criteria is encapsulated within the conditional decision. However, `createCatalogConditionalDecision` will not compile unless `request.permission` is a catalog entity [`ResourcePermission`](https://backstage.io/api/stable/types/_backstage_plugin-permission-common.ResourcePermission.html). This type constraint ensures that policies return conditional decisions that are compatible with the requested permission. To address this, we use [`isPermission`](https://backstage.io/api/stable/functions/_backstage_plugin-permission-common.isPermission.html) to ["narrow"](https://www.typescriptlang.org/docs/handbook/2/narrowing.html) the type of `request.permission` to `ResourcePermission<'catalog-entity'>`. This matches the runtime behavior that was in place before, but you'll notice that the type of `request.permission` has changed within the scope of that `if` statement. -The `catalogConditions` object contains all of the rules defined by the catalog plugin. These rules can be combined to form a [`PermissionCriteria`](https://backstage.io/docs/reference/plugin-permission-common.permissioncriteria) object, but for this case we only need to use the `isEntityOwner` rule. This rule accepts a list of entity refs that represent User identity and Group membership used to determine ownership. The second argument to `PermissionPolicy#handle` provides us with a `PolicyQueryUser` object, from which we can grab the user's `ownershipEntityRefs`. We provide an empty array as a fallback since the user may be anonymous. +The `catalogConditions` object contains all of the rules defined by the catalog plugin. These rules can be combined to form a [`PermissionCriteria`](https://backstage.io/api/stable/types/_backstage_plugin-permission-common.PermissionCriteria.html) object, but for this case we only need to use the `isEntityOwner` rule. This rule accepts a list of entity refs that represent User identity and Group membership used to determine ownership. The second argument to `PermissionPolicy#handle` provides us with a `PolicyQueryUser` object, from which we can grab the user's `ownershipEntityRefs`. We provide an empty array as a fallback since the user may be anonymous. You should now be able to see in your Backstage app that the unregister entity button is enabled for entities that you own, but disabled for all other entities! @@ -190,7 +190,7 @@ class CustomPermissionPolicy implements PermissionPolicy { } ``` -In this example, we use [`isResourcePermission`](https://backstage.io/docs/reference/plugin-permission-common.isresourcepermission) to match all permissions with a resource type of `catalog-entity`. Just like `isPermission`, this helper will "narrow" the type of `request.permission` and enable the use of `createCatalogConditionalDecision`. In addition to the behavior you observed before, you should also see that catalog entities are no longer visible unless you are the owner - success! +In this example, we use [`isResourcePermission`](https://backstage.io/api/stable/functions/_backstage_plugin-permission-common.isResourcePermission.html) to match all permissions with a resource type of `catalog-entity`. Just like `isPermission`, this helper will "narrow" the type of `request.permission` and enable the use of `createCatalogConditionalDecision`. In addition to the behavior you observed before, you should also see that catalog entities are no longer visible unless you are the owner - success! :::note Note diff --git a/docs/plugins/analytics.md b/docs/plugins/analytics.md index f383e8881c..3e8d5b4111 100644 --- a/docs/plugins/analytics.md +++ b/docs/plugins/analytics.md @@ -54,7 +54,7 @@ learn how to contribute the integration yourself! [matomo]: https://github.com/backstage/community-plugins/blob/main/workspaces/analytics/plugins/analytics-module-matomo/README.md [add-tool]: https://github.com/backstage/backstage/issues/new?assignees=&labels=plugin&template=plugin_template.md&title=%5BAnalytics+Module%5D+THE+ANALYTICS+TOOL+TO+INTEGRATE [int-howto]: #writing-integrations -[analytics-api-type]: https://backstage.io/docs/reference/core-plugin-api.analyticsapi +[analytics-api-type]: https://backstage.io/api/stable/types/_backstage_core-plugin-api.index.AnalyticsApi.html [generic-http]: https://github.com/pfeifferj/backstage-plugin-analytics-generic/blob/main/README.md ## Key Events diff --git a/docs/plugins/feature-flags.md b/docs/plugins/feature-flags.md index 3afb8081d5..e9e000df0d 100644 --- a/docs/plugins/feature-flags.md +++ b/docs/plugins/feature-flags.md @@ -55,7 +55,7 @@ The user's selection is saved in the user's browser local storage. Once a featur ## FeatureFlagged Component -The easiest way to control content based on the state of a feature flag is to use the [FeatureFlagged](https://backstage.io/docs/reference/core-app-api.featureflagged) component. +The easiest way to control content based on the state of a feature flag is to use the [FeatureFlagged](https://backstage.io/api/stable/functions/_backstage_core-app-api.FeatureFlagged.html) component. ```ts import { FeatureFlagged } from '@backstage/core-app-api'; @@ -73,7 +73,7 @@ import { FeatureFlagged } from '@backstage/core-app-api'; ## Evaluating Feature Flag State -It is also possible to query a feature flag using the [FeatureFlags Api](https://backstage.io/docs/reference/core-plugin-api.featureflagsapi). +It is also possible to query a feature flag using the [FeatureFlags Api](https://backstage.io/api/stable/interfaces/_backstage_core-plugin-api.index.FeatureFlagsApi.html). ```ts import { useApi, featureFlagsApiRef } from '@backstage/core-plugin-api'; diff --git a/docs/plugins/integrating-search-into-plugins.md b/docs/plugins/integrating-search-into-plugins.md index ec1c4e7a5a..fd80e0a1eb 100644 --- a/docs/plugins/integrating-search-into-plugins.md +++ b/docs/plugins/integrating-search-into-plugins.md @@ -237,7 +237,7 @@ backend.start(); #### 8. Testing the collator code -To verify your implementation works as expected make sure to add tests for it. For your convenience, there is the [`TestPipeline`](https://backstage.io/docs/reference/plugin-search-backend-node.testpipeline) utility that emulates a pipeline into which you can integrate your custom collator. +To verify your implementation works as expected make sure to add tests for it. For your convenience, there is the [`TestPipeline`](https://backstage.io/api/stable/classes/_backstage_plugin-search-backend-node.index.TestPipeline.html) utility that emulates a pipeline into which you can integrate your custom collator. Look at [DefaultTechDocsCollatorFactory test](https://github.com/backstage/backstage/blob/de294ce5c410c9eb56da6870a1fab795268f60e3/plugins/techdocs-backend/src/search/DefaultTechDocsCollatorFactory.test.ts), for an example. @@ -282,7 +282,7 @@ search experience. of state necessary to perform search queries and display any results. As inputs to the query are updated (e.g. a `term` or `filter` values), the updated query is executed and `results` are refreshed. Check out the - [SearchContextValue](https://backstage.io/docs/reference/plugin-search-react.searchcontextvalue) + [SearchContextValue](https://backstage.io/api/stable/types/_backstage_plugin-search-react.index.SearchContextValue.html) for details. - The aforementioned state can be modified and/or consumed via the `useSearch()` hook, also exported by `@backstage/plugin-search-react`. diff --git a/docs/releases/v1.37.0.md b/docs/releases/v1.37.0.md index 8363731292..fc588f83e2 100644 --- a/docs/releases/v1.37.0.md +++ b/docs/releases/v1.37.0.md @@ -99,7 +99,7 @@ There’s also some more information in the [changeset](https://github.com/backs ### New Frontend System improvements -There’s now [a `DialogApi`](https://backstage.io/docs/reference/frontend-plugin-api.dialogapi/), which greatly helps with placing dialogs in front of your users - in particular from code that lives outside the React tree, such as in callbacks. +There’s now [a `DialogApi`](https://backstage.io/api/stable/interfaces/_backstage_frontend-plugin-api.index.DialogApi.html), which greatly helps with placing dialogs in front of your users - in particular from code that lives outside the React tree, such as in callbacks. At the same time, an `EntityHeaderBlueprint` lets you specifically replace the entity page headers. You can now also group multiple entity page contents into a single tab. A tab that groups more than one entity content is rendered as a dropdown menu. You can use the default list of tab groups or create your own. Groups are sorted in the same order as they are defined in the `app-config.yaml` file. The association between an entity content and a tab group can be optionally done when creating the content extension or via the `app-config.yaml` file. See usage examples in the [#28701](https://github.com/backstage/backstage/pull/28701) and [#29043](https://github.com/backstage/backstage/pull/29043) pull requests. diff --git a/microsite/blog/2023-01-31-incremental-entity-provider.mdx b/microsite/blog/2023-01-31-incremental-entity-provider.mdx index 8138b8a39a..2121c3f950 100644 --- a/microsite/blog/2023-01-31-incremental-entity-provider.mdx +++ b/microsite/blog/2023-01-31-incremental-entity-provider.mdx @@ -16,7 +16,7 @@ Data is transformed into entities via what is known as the ingestion and process ## Entity Providers -Backstage offers what are known as [entity providers](https://backstage.io/docs/features/software-catalog/life-of-an-entity) as a means for ingesting the raw data into the pipeline and transforming them into Backstage entities. For example, Backstage comes with a [GitHub Entity Provider](https://backstage.io/docs/reference/plugin-catalog-backend-module-github) that finds all catalog-info.yaml files in GitHub repositories. The processing loop transforms them into Backstage entities and subsequently persists them to the software catalog. +Backstage offers what are known as [entity providers](https://backstage.io/docs/features/software-catalog/life-of-an-entity) as a means for ingesting the raw data into the pipeline and transforming them into Backstage entities. For example, Backstage comes with a [GitHub Entity Provider](https://backstage.io/api/stable/modules/_backstage_plugin-catalog-backend-module-github.html) that finds all catalog-info.yaml files in GitHub repositories. The processing loop transforms them into Backstage entities and subsequently persists them to the software catalog. Entity providers are a relatively new abstraction and the recommended way to ingest data into the catalog. The Backstage catalog engine starts each registered entity provider, which connects to its data source (e.g., the GitHub Entity Provider connects to GitHub). The entity provider will query the external data source and convert the data into the entity format. Finally, the entity provider issues what is known as a mutation to the catalog engine. A mutation is a signal from the entity provider to the catalog engine that entities are available to be processed and stored. diff --git a/microsite/blog/2024-06-27-backstage-engineer-journey.mdx b/microsite/blog/2024-06-27-backstage-engineer-journey.mdx index 9180a4b6d7..d0aea4ca50 100644 --- a/microsite/blog/2024-06-27-backstage-engineer-journey.mdx +++ b/microsite/blog/2024-06-27-backstage-engineer-journey.mdx @@ -61,7 +61,7 @@ My goal has changed from being a contributor to being the driver, i.e., from doi At Spotify, we expect engineers to use technologies approved by our [Tech Radar](https://backstage.io/blog/2020/05/14/tech-radar-plugin/#what-is-tech-radar) and follow the best quality standards. -To do so, we use a plugin called [Scaffolder](https://backstage.io/docs/reference/plugin-scaffolder) (aka Software Templates), which allows engineers to create templates for setting up new projects. Templates automate actions such as creating repositories, allocating resources, registering in the catalog, configuring deployments, and connecting to other internal systems. +To do so, we use a plugin called [Scaffolder](https://backstage.io/api/stable/modules/_backstage_plugin-scaffolder.html) (aka Software Templates), which allows engineers to create templates for setting up new projects. Templates automate actions such as creating repositories, allocating resources, registering in the catalog, configuring deployments, and connecting to other internal systems. > **Reflection:**
    _“Do you need to create a ticket to get these things done before you even start coding? And is there a lot of time spent looking for boilerplate code to start a new project and connecting it to other internal systems?"_ diff --git a/plugins/catalog-backend/src/schema/openapi.yaml b/plugins/catalog-backend/src/schema/openapi.yaml index e4282f1700..c758ef7b3d 100644 --- a/plugins/catalog-backend/src/schema/openapi.yaml +++ b/plugins/catalog-backend/src/schema/openapi.yaml @@ -6,7 +6,7 @@ info: The API surface consists of a few distinct groups of functionality. Each has a dedicated section below. - :::note Note + :::note Note This page only describes some of the most commonly used parts of the API, and is a work in progress. ::: @@ -20,7 +20,7 @@ info: Some or all of the endpoints may accept or require an `Authorization` header with a `Bearer` token, which should then be the Backstage token returned by the - [`identity API`](https://backstage.io/docs/reference/core-plugin-api.identityapiref). + [`identity API`](https://backstage.io/api/stable/variables/_backstage_core-plugin-api.index.identityApiRef.html). license: name: Apache-2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html diff --git a/plugins/catalog-backend/src/schema/openapi/generated/router.ts b/plugins/catalog-backend/src/schema/openapi/generated/router.ts index fddec71822..392299c605 100644 --- a/plugins/catalog-backend/src/schema/openapi/generated/router.ts +++ b/plugins/catalog-backend/src/schema/openapi/generated/router.ts @@ -26,7 +26,7 @@ export const spec = { title: 'catalog', version: '1', description: - 'The API surface consists of a few distinct groups of functionality. Each has a\ndedicated section below.\n\n:::note Note \n This page only describes some of the most commonly used parts of the API, and is a work in progress.\n:::\n\nAll of the URL paths in this article are assumed to be on top of some base URL\npointing at your catalog installation. For example, if the path given in a\nsection below is `/entities`, and the catalog is located at\n`http://localhost:7007/api/catalog` during local development, the full URL would\nbe `http://localhost:7007/api/catalog/entities`. The actual URL may vary from\none organization to the other, especially in production, but is commonly your\n`backend.baseUrl` in your app config, plus `/api/catalog` at the end.\n\nSome or all of the endpoints may accept or require an `Authorization` header\nwith a `Bearer` token, which should then be the Backstage token returned by the\n[`identity API`](https://backstage.io/docs/reference/core-plugin-api.identityapiref).\n', + 'The API surface consists of a few distinct groups of functionality. Each has a\ndedicated section below.\n\n:::note Note \n This page only describes some of the most commonly used parts of the API, and is a work in progress.\n:::\n\nAll of the URL paths in this article are assumed to be on top of some base URL\npointing at your catalog installation. For example, if the path given in a\nsection below is `/entities`, and the catalog is located at\n`http://localhost:7007/api/catalog` during local development, the full URL would\nbe `http://localhost:7007/api/catalog/entities`. The actual URL may vary from\none organization to the other, especially in production, but is commonly your\n`backend.baseUrl` in your app config, plus `/api/catalog` at the end.\n\nSome or all of the endpoints may accept or require an `Authorization` header\nwith a `Bearer` token, which should then be the Backstage token returned by the\n[`identity API`](https://backstage.io/api/stable/variables/_backstage_core-plugin-api.index.identityApiRef.html).\n', license: { name: 'Apache-2.0', url: 'http://www.apache.org/licenses/LICENSE-2.0.html', diff --git a/plugins/catalog-graph/README-alpha.md b/plugins/catalog-graph/README-alpha.md index bc5cea3fd1..f2e17cb42c 100644 --- a/plugins/catalog-graph/README-alpha.md +++ b/plugins/catalog-graph/README-alpha.md @@ -132,7 +132,7 @@ An [entity card](https://backstage.io/docs/frontend-system/building-plugins/exte ##### Output -A React component defined by the [coreExtensionData.reactElement](https://backstage.io/docs/reference/frontend-plugin-api.coreextensiondata/) type. +A React component defined by the [coreExtensionData.reactElement](https://backstage.io/api/stable/variables/_backstage_frontend-plugin-api.index.coreExtensionData.html) type. ##### Inputs @@ -232,7 +232,7 @@ A [page](https://backstage.io/docs/reference/frontend-plugin-api.createapiextens ##### Output -A React component defined by the [coreExtensionData.reactElement](https://backstage.io/docs/reference/frontend-plugin-api.coreextensiondata/) type. +A React component defined by the [coreExtensionData.reactElement](https://backstage.io/api/stable/variables/_backstage_frontend-plugin-api.index.coreExtensionData.html) type. ##### Inputs diff --git a/plugins/mcp-actions-backend/README.md b/plugins/mcp-actions-backend/README.md index 39ec169dec..c2eba60c80 100644 --- a/plugins/mcp-actions-backend/README.md +++ b/plugins/mcp-actions-backend/README.md @@ -75,7 +75,7 @@ export const myPlugin = createBackendPlugin({ When errors are thrown from MCP actions, the backend will handle and surface error message for any error from `@backstage/errors`. Unknown errors will be handled by `@modelcontextprotocol/sdk`'s default error handling, which may result in a generic `500 Server Error` being returned. As a result, we recommend using errors from `@backstage/errors` when applicable. -See https://backstage.io/docs/reference/errors/ for a full list of supported errors. +See https://backstage.io/api/stable/modules/_backstage_errors.html for a full list of supported errors. When writing MCP tools, use the appropriate error from `@backstage/errors` when applicable: diff --git a/plugins/scaffolder-backend/sample-templates/bitbucket-demo/template.yaml b/plugins/scaffolder-backend/sample-templates/bitbucket-demo/template.yaml index c8f85974ea..a05411a7d0 100644 --- a/plugins/scaffolder-backend/sample-templates/bitbucket-demo/template.yaml +++ b/plugins/scaffolder-backend/sample-templates/bitbucket-demo/template.yaml @@ -21,7 +21,7 @@ spec: allowedHosts: - bitbucket.org # The rest of these options are optional. - # You can read more at: https://backstage.io/docs/reference/plugin-scaffolder.repourlpickerfieldextension + # You can read more at: https://backstage.io/api/stable/variables/_backstage_plugin-scaffolder.index.RepoUrlPickerFieldExtension.html # allowedOwners: # - WORKSPACE1 # - WORKSPACE2