docs: sunset the docs/plugins section as legacy documentation
Mark all pages in docs/plugins/ with legacy admonition banners pointing to the appropriate new frontend system and backend system documentation. Rename the sidebar section to "Plugins (Legacy)" and move it lower in the navigation hierarchy. Add cross-references from the new frontend system building-plugins guide to relevant cross-cutting topics (i18n, analytics, feature flags, search) that still live in the legacy section. Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com> Made-with: Cursor
This commit is contained in:
Patrik Oldsberg
@@ -4,6 +4,12 @@ title: Add to Directory
|
||||
description: Documentation on Adding Plugin to Plugin Directory
|
||||
---
|
||||
|
||||
:::caution Legacy Documentation
|
||||
|
||||
This section is part of the legacy plugins documentation. The process for adding plugins to the directory described here is still current.
|
||||
|
||||
:::
|
||||
|
||||
## Adding a Plugin to the Directory
|
||||
|
||||
To add a new plugin to the [plugin directory](https://backstage.io/plugins) create a file with the following pattern `<plugin-name>.yaml` where `<plugin-name>` is the name of your plugin. This file will go in [`microsite/data/plugins`](https://github.com/backstage/backstage/tree/master/microsite/data/plugins) with your plugin's information. Example:
|
||||
|
||||
@@ -4,6 +4,12 @@ title: Plugin Analytics
|
||||
description: Measuring usage of your Backstage instance.
|
||||
---
|
||||
|
||||
:::caution Legacy Documentation
|
||||
|
||||
This section is part of the legacy plugins documentation. The concepts and events described here apply to both the old and new frontend systems. However, the "Writing Integrations" section shows examples for both the old frontend system (`createApiFactory`) and the new frontend system (`AnalyticsImplementationBlueprint`). For new development, prefer the new frontend system approach. See also [Utility APIs](../frontend-system/utility-apis/01-index.md).
|
||||
|
||||
:::
|
||||
|
||||
Setting up, maintaining, and iterating on an instance of Backstage can be a
|
||||
large investment. To help measure return on this investment, Backstage comes
|
||||
with an event-based Analytics API that grants app integrators the flexibility to
|
||||
|
||||
@@ -4,6 +4,12 @@ title: Backend plugins
|
||||
description: Creating and Developing Backend plugins
|
||||
---
|
||||
|
||||
:::caution Legacy Documentation
|
||||
|
||||
This section is part of the legacy plugins documentation. While this page already describes the new backend system patterns, the canonical documentation for building backend plugins has moved to [Building Backend Plugins and Modules](../backend-system/building-plugins-and-modules/01-index.md).
|
||||
|
||||
:::
|
||||
|
||||
This page describes the process of creating and managing backend plugins in your
|
||||
Backstage repository.
|
||||
|
||||
|
||||
@@ -4,6 +4,12 @@ title: Call Existing API
|
||||
description: Describes the various options that Backstage frontend plugins have, in communicating with service APIs that already exist
|
||||
---
|
||||
|
||||
:::caution Legacy Documentation
|
||||
|
||||
This section is part of the legacy plugins documentation. The frontend code examples on this page use the old frontend system APIs (`discoveryApiRef`, `fetchApiRef` from `@backstage/core-plugin-api`). The same APIs are available in the new frontend system via `@backstage/frontend-plugin-api`. The general guidance on when to use direct requests vs. the proxy vs. a backend plugin remains valid for both systems.
|
||||
|
||||
:::
|
||||
|
||||
This article describes the various options that Backstage frontend plugins have,
|
||||
in communicating with service APIs that already exist. Each section below
|
||||
describes a possible choice, and the circumstances under which it fits.
|
||||
|
||||
@@ -4,6 +4,12 @@ title: Composability System
|
||||
description: Documentation for the Backstage plugin composability APIs.
|
||||
---
|
||||
|
||||
:::caution Legacy Documentation
|
||||
|
||||
This page describes the composability system for the **old frontend system**, including `createRoutableExtension`, `createComponentExtension`, `RouteRef`, `ExternalRouteRef`, and component data. For the new frontend system, see [Extensions](../frontend-system/architecture/20-extensions.md), [Extension Blueprints](../frontend-system/architecture/23-extension-blueprints.md), and [Routes](../frontend-system/architecture/36-routes.md).
|
||||
|
||||
:::
|
||||
|
||||
## Summary
|
||||
|
||||
This page describes the composability system that helps bring together content
|
||||
|
||||
@@ -4,6 +4,12 @@ title: Create a Backstage Plugin
|
||||
description: Documentation on How to Create a Backstage Plugin
|
||||
---
|
||||
|
||||
:::caution Legacy Documentation
|
||||
|
||||
This page describes creating plugins for the **old frontend system**. For creating plugins using the new frontend system, see [Building Frontend Plugins](../frontend-system/building-plugins/01-index.md). For creating backend plugins, see [Building Backend Plugins and Modules](../backend-system/building-plugins-and-modules/01-index.md).
|
||||
|
||||
:::
|
||||
|
||||
A Backstage Plugin adds functionality to Backstage.
|
||||
|
||||
## Create a Plugin
|
||||
|
||||
@@ -4,6 +4,12 @@ title: Feature Flags
|
||||
description: Details the process of defining setting and reading a feature flag.
|
||||
---
|
||||
|
||||
:::caution Legacy Documentation
|
||||
|
||||
This page describes feature flags using the **old frontend system** APIs (`createPlugin` from `@backstage/core-plugin-api` and `createApp` from `@backstage/app-defaults`). For the new frontend system, feature flags are declared via the `featureFlags` option in `createFrontendPlugin` — see [Building Frontend Plugins](../frontend-system/building-plugins/01-index.md). The `FeatureFlagged` component and `featureFlagsApiRef` work the same way in both systems.
|
||||
|
||||
:::
|
||||
|
||||
Backstage offers the ability to define feature flags inside a plugin or during application creation. This allows you to restrict parts of your plugin to those individual users who have toggled the feature flag to on.
|
||||
|
||||
This page describes the process of defining, setting and reading a feature flag. If you are looking for using feature flags specifically with software templates please see [Writing Templates](https://backstage.io/docs/features/software-templates/writing-templates#remove-sections-or-fields-based-on-feature-flags).
|
||||
|
||||
@@ -1,9 +1,15 @@
|
||||
---
|
||||
id: index
|
||||
title: Introduction to Plugins
|
||||
description: Learn about integrating various infrastructure and software development tools into Backstage through plugins.
|
||||
title: Introduction to Plugins (Legacy)
|
||||
description: Legacy documentation for integrating various infrastructure and software development tools into Backstage through plugins using the old frontend system.
|
||||
---
|
||||
|
||||
:::caution Legacy Documentation
|
||||
|
||||
This section covers plugin development using the **old frontend system**. For new development, please refer to the [new frontend system](../frontend-system/index.md) and [new backend system](../backend-system/index.md) documentation. The content here is kept for reference and for maintaining existing plugins that have not yet been migrated.
|
||||
|
||||
:::
|
||||
|
||||
Backstage orchestrates a cohesive single-page application by seamlessly integrating various plugins.
|
||||
|
||||
Our vision for the plugin ecosystem champions flexibility, empowering you to incorporate a broad spectrum of infrastructure and software development tools into Backstage as plugins. Adherence to stringent [design guidelines](../dls/design.md) guarantees a consistent and intuitive user experience across the entire plugin landscape.
|
||||
|
||||
@@ -4,6 +4,12 @@ title: Integrate into the Software Catalog
|
||||
description: How to integrate a plugin into software catalog
|
||||
---
|
||||
|
||||
:::caution Legacy Documentation
|
||||
|
||||
This page describes integrating plugins into the Software Catalog using the **old frontend system** patterns (`EntitySwitch`, `EntityLayout`, `EntityLayout.Route`). For the new frontend system, entity page integrations are done using `EntityCardBlueprint` and `EntityContentBlueprint` — see [Common Extension Blueprints](../frontend-system/building-plugins/03-common-extension-blueprints.md).
|
||||
|
||||
:::
|
||||
|
||||
> This is an advanced use case and currently is an experimental feature. Expect
|
||||
> API to change over time
|
||||
|
||||
|
||||
@@ -4,6 +4,12 @@ title: Integrating Search into a plugin
|
||||
description: How to integrate Search into a Backstage plugin
|
||||
---
|
||||
|
||||
:::caution Legacy Documentation
|
||||
|
||||
This section is part of the legacy plugins documentation. The backend search collator patterns described here use the new backend system and are still current. The frontend search experience examples use the old frontend system APIs. For the new frontend system, search result list items are created using `SearchResultListItemBlueprint` — see [Common Extension Blueprints](../frontend-system/building-plugins/03-common-extension-blueprints.md).
|
||||
|
||||
:::
|
||||
|
||||
The Backstage Search Platform was designed to give plugin developers the APIs
|
||||
and interfaces needed to offer search experiences within their plugins, while
|
||||
abstracting away (and instead empowering application integrators to choose) the
|
||||
|
||||
@@ -4,6 +4,12 @@ title: Internationalization
|
||||
description: Documentation on adding internationalization to plugins and apps
|
||||
---
|
||||
|
||||
:::caution Legacy Documentation
|
||||
|
||||
This section is part of the legacy plugins documentation. The i18n APIs (`createTranslationRef`, `useTranslationRef`) work the same way in both the old and new frontend systems. The "For an application developer" section already shows the new frontend system approach using `createTranslationResource` from `@backstage/frontend-plugin-api`.
|
||||
|
||||
:::
|
||||
|
||||
## Overview
|
||||
|
||||
The Backstage core function provides internationalization for plugins and apps. The underlying library is [`i18next`](https://www.i18next.com/) with some additional Backstage typescript magic for type safety with keys.
|
||||
|
||||
@@ -4,6 +4,12 @@ title: New Backend System
|
||||
description: Details of the new backend system
|
||||
---
|
||||
|
||||
:::caution Legacy Documentation
|
||||
|
||||
This section is part of the legacy plugins documentation. The canonical documentation for the backend system has moved to the [Backend System](../backend-system/index.md) section, which includes more detailed and up-to-date guides for [building plugins and modules](../backend-system/building-plugins-and-modules/01-index.md), [architecture](../backend-system/architecture/01-index.md), and [core services](../backend-system/core-services/01-index.md).
|
||||
|
||||
:::
|
||||
|
||||
## Status
|
||||
|
||||
The new backend system is released and ready for production use, and many plugins and modules have already been migrated. We recommend all plugins and deployments to migrate to the new system.
|
||||
|
||||
@@ -4,6 +4,12 @@ title: Observability
|
||||
description: Adding Observability to Your Plugin
|
||||
---
|
||||
|
||||
:::caution Legacy Documentation
|
||||
|
||||
This section is part of the legacy plugins documentation. For new backend system logging, see the [Logger](../backend-system/core-services/logger.md) and [Root Logger](../backend-system/core-services/root-logger.md) core service documentation. For health checks, see [Root Health](../backend-system/core-services/root-health.md).
|
||||
|
||||
:::
|
||||
|
||||
This article briefly describes the observability options that are available to a
|
||||
Backstage integrator.
|
||||
|
||||
|
||||
@@ -4,6 +4,12 @@ title: Plugin Development
|
||||
description: Documentation on Plugin Development
|
||||
---
|
||||
|
||||
:::caution Legacy Documentation
|
||||
|
||||
This page covers plugin development patterns for the **old frontend system**, including `createPlugin`, `createRoutableExtension`, and `RouteRef` from `@backstage/core-plugin-api`. For the new frontend system equivalents, see [Building Frontend Plugins](../frontend-system/building-plugins/01-index.md) and [Routes](../frontend-system/architecture/36-routes.md).
|
||||
|
||||
:::
|
||||
|
||||
Backstage plugins provide features to a Backstage App.
|
||||
|
||||
Each plugin is treated as a self-contained web app and can include almost any
|
||||
|
||||
@@ -4,6 +4,12 @@ title: Plugin Directory Audit
|
||||
description: Details about the process for auditing plugins in the directory
|
||||
---
|
||||
|
||||
:::caution Legacy Documentation
|
||||
|
||||
This section is part of the legacy plugins documentation. The audit process described here is still current.
|
||||
|
||||
:::
|
||||
|
||||
## Audit Process
|
||||
|
||||
We have a simple process in place to audit the plugins in the Plugin Directory:
|
||||
|
||||
@@ -4,6 +4,12 @@ title: Proxying
|
||||
description: Documentation on Proxying
|
||||
---
|
||||
|
||||
:::caution Legacy Documentation
|
||||
|
||||
This section is part of the legacy plugins documentation. The proxy configuration and usage described here applies to both the old and new backend systems. For creating backend plugins and modules, see [Building Backend Plugins and Modules](../backend-system/building-plugins-and-modules/01-index.md).
|
||||
|
||||
:::
|
||||
|
||||
This page describes how to configure and use the built-in HTTP proxy functionality in your Backstage backend.
|
||||
|
||||
## Overview
|
||||
|
||||
@@ -4,4 +4,10 @@ title: Publish private
|
||||
description: Documentation on How to Publish private
|
||||
---
|
||||
|
||||
:::caution Legacy Documentation
|
||||
|
||||
This section is part of the legacy plugins documentation.
|
||||
|
||||
:::
|
||||
|
||||
## TODO
|
||||
|
||||
@@ -4,6 +4,12 @@ title: Structure of a Plugin
|
||||
description: Details about structure of a plugin
|
||||
---
|
||||
|
||||
:::caution Legacy Documentation
|
||||
|
||||
This page describes the structure of a plugin for the **old frontend system**. For the new frontend system, see [Building Frontend Plugins](../frontend-system/building-plugins/01-index.md). The general folder structure is similar, but the plugin wiring in `plugin.ts` differs significantly.
|
||||
|
||||
:::
|
||||
|
||||
Nice, you have a new plugin! We'll soon see how we can develop it into doing
|
||||
great things. But first off, let's look at what we get out of the box.
|
||||
|
||||
|
||||
@@ -4,6 +4,12 @@ title: Testing with Jest
|
||||
description: Documentation on How to do unit testing with Jest
|
||||
---
|
||||
|
||||
:::caution Legacy Documentation
|
||||
|
||||
This section is part of the legacy plugins documentation. The general testing principles described here still apply, but for system-specific testing guides, see [Testing Frontend Plugins](../frontend-system/building-plugins/02-testing.md) and [Testing Backend Plugins and Modules](../backend-system/building-plugins-and-modules/02-testing.md).
|
||||
|
||||
:::
|
||||
|
||||
:::note Note
|
||||
|
||||
You may want to consider migrating to Jest 30, to do this, you can follow this guide: [Migrating to Jest 30](../tutorials/jest30-migration.md)
|
||||
|
||||
Reference in New Issue
Block a user