some minor doc tweaks

Signed-off-by: Fredrik Adelöw <freben@gmail.com>

docs/frontend-system/architecture/05-extension-overrides.md

@@ -12,7 +12,7 @@ description: Frontend extension overrides
 
 An extension override is a building block of the frontend system that allows you to programmatically override app or plugin extensions anywhere in your application. Since the entire application is built mostly out of extensions from the bottom up, this is a powerful feature. You can use it for example to provide your own app root layout, to replace the implementation of a Utility API with a custom one, to override how the catalog page renders itself, and much more.
 
-In general, most features should have a good level of customization built into them, so that users do not have to leverage extension overrides to achieve common goals. A well written feature often has `app-config` settings, or uses extension inputs for extensibility where applicable. An example of this is the search plugin, which allows you to provide result renderers as inputs rather than replacing the result page wholesale just to tweak how results are shown. Adopters should take advantage of those when possible, and only use extension overrides when it's necessary to entirely replace the extension. Check the respective extension documentation for guidance.
+In general, most features should have a good level of customization built into them, so that users do not have to leverage extension overrides to achieve common goals. A well written feature often has [configuration](../../conf/) settings, or uses extension inputs for extensibility where applicable. An example of this is the search plugin, which allows you to provide result renderers as inputs rather than replacing the result page wholesale just to tweak how results are shown. Adopters should take advantage of those when possible, and only use extension overrides when it's necessary to entirely replace the extension. Check the respective extension documentation for guidance.
 
 ## Override App Extensions
 
@@ -74,7 +74,7 @@ import themeOverrides from './themes';
 
 const app = createApp({
   // highlight-next-line
- features: [ themeOverrides ],
+ features: [themeOverrides],
 });
 
 export default app.createRoot().

docs/frontend-system/architecture/07-routes.md

@@ -10,15 +10,15 @@ description: Frontend routes
 
 ## Introduction
 
-Each Backstage plugin is an isolated piece of functionality that doesn't typically communicate directly with other plugins. In order to achieve this, there are many parts of the frontend system that provide a layer of indirection for cross-plugin communication, and they routing system is one of them.
+Each Backstage plugin is an isolated piece of functionality that doesn't typically communicate directly with other plugins. In order to achieve this, there are many parts of the frontend system that provide a layer of indirection for cross-plugin communication, and the routing system is one of them.
 
 The Backstage routing system makes it possible to implement navigation across plugin boundaries, without each individual plugin knowing the concrete path or location of other plugins in the routing hierarchy, or even its own. This is achieved through the concept of route references, which are opaque reference values that can be shared and used to create concrete links to different parts of an app. The route ref paths can be configured both at plugin level (by plugin developers) and at the app level (by integrators). It is up to plugin developers to create route references for any page content in their plugin that they want it to be possible to link to or from.
 
 ## Route References
 
-Plugin developers create a `RouteRef` to expose a path in Backstage's routing system. You will see below how routes are defined programmatically, but before diving into code, let us explain how to configure them at app level. In spite of the fact that plugin developers choose a default route path for the routes their plugin provides, paths are configurable, so app integrators can set a custom path to a route whenever they like to (more information in the following sections).
+Plugin developers create a `RouteRef` to expose a path in Backstage's routing system. You will see below how routes are defined programmatically, but before diving into code, let us explain how to configure them at the app level. In spite of the fact that plugin developers choose a default route path for the routes their plugin provides, paths are configurable, so app integrators can set a custom path to a route whenever they like to (more information in the following sections).
 
-There are 3 types of route references: regular route, sub route, and external route, and we will cover both the concept and code definition for each.
+There are three types of route references: regular route, sub route, and external route, and we will cover both the concept and code definition for each.
 
 ### Creating a Route Reference
 
@@ -31,7 +31,7 @@ import { createRouteRef } from '@backstage/frontend-plugin-api';
 export const indexRouteRef = createRouteRef();
 ```
 
-Note that you often want to create the route references themselves in a different file than the one that creates the plugin instance, for example a top-level routes.ts. This is to avoid circular imports when you use the route references from other parts of the same plugin.
+Note that you often want to create the route references themselves in a different file than the one that creates the plugin instance, for example a top-level `routes.ts`. This is to avoid circular imports when you use the route references from other parts of the same plugin.
 
 Route refs do not have any behavior themselves. They are an opaque value that represents route targets in an app, which are bound to specific paths at runtime. Their role is to provide a level of indirection to help link together different pages that otherwise wouldn't know how to route to each other.
 
@@ -68,7 +68,7 @@ export default createPlugin({
 
 In the example above we associated the `indexRouteRef` with the `catalogIndexPage` extension and provided both the route ref and page via the Catalog plugin. So, When this plugin is installed in the app, the index page will become associated with the newly created `RouteRef`, making it possible to use the route ref to navigate the page extension.
 
-It may be unclear why we configure the routes option when creating a plugin as the route has already been passed to the extension. We do that to make it possible for other plugins to route to our page, which is explained in detail in the [binding routes](#binding-external-route-references) section.
+It may seem unclear why we configure the `routes` option when creating a plugin as the route has already been passed to the extension. We do that to make it possible for other plugins to route to our page, which is explained in detail in the [binding routes](#binding-external-route-references) section.
 
 ### Defining References with Path Parameters
 
@@ -86,7 +86,7 @@ export const detailsRouteRef = createRouteRef({
 
 ### Using a Route Reference
 
-Route references can be used to link to page in the same plugin, or to pages in a different plugins. In this section we will cover the first scenario, if you are interested in link to a page of a different plugin, please go to the [external routes](#external-router-references) section below.
+Route references can be used to link to page in the same plugin, or to pages in different plugins. In this section we will cover the first scenario. If you are interested in linking to a page of a different plugin, please go to the [external routes](#external-route-references) section below.
 
 Suppose we are creating a plugin that renders a Catalog index page with a link to a "Foo" component details page. Here is the code for the index page:
 
@@ -117,7 +117,7 @@ export const IndexPage = () => {
 };
 ```
 
-We use the `useRouteRef` hook to create a link generator function that returns the details page path. We then call the link generator, passing it an object with the kind, namespace, and name. These parameters are used to construct a concrete path to details the "Foo" details page.
+We use the `useRouteRef` hook to create a link generator function that returns the details page path. We then call the link generator, passing it an object with the kind, namespace, and name. These parameters are used to construct a concrete path to the "Foo" details page.
 
 Let's see how the details page can get the parameters from the URL:
 
@@ -148,12 +148,12 @@ In the code above, we are using the `useRouteRefParams` hook to retrieve the ent
 
 Since we are linking to pages of the same package, we are using a route ref directly. However, in the following sections, you will see how to link to pages of different plugins.
 
-## External Router References
+## External Route References
 
 External routes are made for linking to a page of an external plugin.
 For this section example, let's assume that we want to link from the Catalog entities list page to the Scaffolder create component page.
 
-We don't want to reference the Scaffolder plugin directly, since that would create an unnecessary dependency. It would also provided little flexibility in allowing the app to tie plugins together, with the links instead being dictated by the plugins themselves. To solve this, we use an `ExternalRouteRef`. Much like regular route references, they can be passed to `useRouteRef` to create concrete URLs, but they can not be used in page extensions and instead have to be associated with a target route using route bindings in the app.
+We don't want to reference the Scaffolder plugin directly, since that would create an unnecessary dependency. It would also provide little flexibility in allowing the app to tie plugins together, with the links instead being dictated by the plugins themselves. To solve this, we use an `ExternalRouteRef`. Much like regular route references, they can be passed to `useRouteRef` to create concrete URLs, but they can not be used in page extensions and instead have to be associated with a target route using route bindings in the app.
 
 We create a new `RouteRef` inside the Scaffolder plugin, using a neutral name that describes its role in the plugin rather than a specific plugin page that it might be linking to, allowing the app to decide the final target. If the Catalog entity list page for example wants to link the Scaffolder create component page in the header, it might declare an `ExternalRouteRef` similar to this:
 
@@ -272,7 +272,7 @@ export default app.createRoot();
 
 Note that we are not importing and using the `RouteRef`s directly in the app, and instead rely on the plugin instance to access routes of the plugins. This provides better namespacing and discoverability of routes, as well as reduce the number of separate exports from each plugin package.
 
-Another thing to note is that this indirection in the routing is particularly useful for open source plugins that need to leave flexibility in how they are integrated. For plugins that you build internally for your own Backstage application, you can choose to go the route of direct imports or even use concrete routes directly. Although there can be some benefits to using the full routing system even in internal plugins. It can help you structure your routes, and as you will see further down it also helps you manage route parameters.
+Another thing to note is that this indirection in the routing is particularly useful for open source plugins that need to provide flexibility in how they are integrated. For plugins that you build internally for your own Backstage application, you can choose to use direct imports or even concrete route path strings directly. Although there can be some benefits to using the full routing system even in internal plugins: it can help you structure your routes, and as you will see further down it also helps you manage route parameters.
 
 ### Optional External Route References
 
@@ -312,7 +312,7 @@ export const IndexPage = () => {
 
 ## Sub Route References
 
-The last kind of route refs that can be created are `SubRouteRef`s, which can be used to create a route ref with a fixed path relative to an absolute `RouteRef`. They are useful if you have a page that internally is mounted at a sub route of a page extension component, and you want other plugins to be able to route to that page. And they can be a useful utility to handle routing within a plugin itself as well.
+The last kind of route ref that can be created is a `SubRouteRef`, which can be used to create a route ref with a fixed path relative to an absolute `RouteRef`. They are useful if you have a page that internally is mounted at a sub route of a page extension component, and you want other plugins to be able to route to that page. And they can be a useful utility to handle routing within a plugin itself as well.
 
 For example:
 

docs/frontend-system/building-plugins/01-index.md

@@ -18,7 +18,9 @@ This guide assumes that you already have a Backstage project set up. Even if you
 
 To create a frontend plugin, run `yarn new`, select `plugin`, and fill out the rest of the prompts. This will create a new package at `plugins/<pluginId>`, which will be the main entrypoint for your plugin.
 
-> **NOTE: The created plugin will currently be templated for use in the legacy frontend system, and you will need to replace the existing plugin wiring code.**
+:::info
+The created plugin will currently be templated for use in the legacy frontend system, and you will need to replace the existing plugin wiring code.
+:::
 
 ## The plugin instance
 
@@ -67,7 +69,7 @@ import {
 } from '@backstage/frontend-plugin-api';
 import { rootRouteRef } from './routes';
 
-// Note that these extensions aren't exported, only the plugin itself it.
+// Note that these extensions aren't exported, only the plugin itself is.
 // You can export it locally for testing purposes, but don't export it from the plugin package.
 const examplePage = createPageExtension({
   routeRef: rootRouteRef,
@@ -104,7 +106,7 @@ export const examplePlugin = createPlugin({
 
 What we've built here is a very common type of plugin. It's a top-level tool that provides a single page, along with a method for navigating to that page. The implementation of the page component, in this case the highlighted `ExamplePage`, can be arbitrarily complex. It can be anything from a single simple information page, to a full-blown application with multiple sub-pages.
 
-We have also provided external access to our route reference by passing it to the plugin `routes` option. This makes it possible for app integrators to bind an external link from a different plugin to our plugin page. You can read more about how this works in the [External Route References](../architecture/07-routes.md#external-router-references) section.
+We have also provided external access to our route reference by passing it to the plugin `routes` option. This makes it possible for app integrators to bind an external link from a different plugin to our plugin page. You can read more about how this works in the [External Route References](../architecture/07-routes.md#external-route-references) section.
 
 ## Utility APIs
 
@@ -141,7 +143,7 @@ export function ExamplePage() {
   return (
     <div>
       <h1>Example Page</h1>
-      <p>Example: {exampleApi.getExample()}</p>
+      <p>Example: {exampleApi.getExample().example}</p>
     </div>
   );
 }
@@ -182,14 +184,14 @@ export const examplePlugin = createPlugin({
 
 ## Plugin specific extensions
 
-There are many different plugins that you can extend with additional functionality through extensions. One such plugin is the catalog plugin, one of the core features of Backstage. It lets you catalog the software in your organization, where each item in the catalog has its own page that can be populated with tools and information relating to that catalog entity. In this example we will explore how our plugin can provide such a tool to display on an entity page.
+There are many different plugins that you can extend with additional functionality through extensions. One such plugin is [the catalog plugin](../../features/software-catalog/), one of the core features of Backstage. It lets you catalog the software in your organization, where each item in the catalog has its own page that can be populated with tools and information relating to that catalog entity. In this example we will explore how our plugin can provide such a tool to display on an entity page.
 
 ```tsx title="in src/plugin.ts - An example entity content extension"
 import { createEntityContentExtension } from '@backstage/plugin-catalog-react';
 
-// Entity content extension are similar to page extensions in that they are rendered at a route,
+// Entity content extensions are similar to page extensions in that they are rendered at a route,
 // although they also have a title to support in-line navigation between the different content.
-// Just like a page extensions the content is lazy loaded, and you can also provide a
+// Just like a page extension the content is lazy loaded, and you can also provide a
 // route reference if you want to be able to generate a URL that links to the content.
 const exampleEntityContent = createEntityContentExtension({
   defaultPath: 'example',
@@ -199,8 +201,22 @@ const exampleEntityContent = createEntityContentExtension({
       <m.ExampleEntityContent />
     )),
 });
+
+export const examplePlugin = createPlugin({
+  id: 'example',
+  extensions: [
+    // highlight-add-next-line
+    exampleEntityContent
+    exampleApi,
+    examplePage,
+    exampleNavItem,
+  ],
+  routes: {
+    root: rootRouteRef,
+  },
+});
 ```
 
-The `ExampleEntityContent` itself is again a regular React component where you can implement any functionality you want. To access the entity that the content is being rendered for, you can use the `useEntity` hook from `@backstage/plugin-catalog-react`. You can see a full list of API provided by the catalog React library in [the API reference](../../reference/plugin-catalog-react.md).
+The `ExampleEntityContent` itself is again a regular React component where you can implement any functionality you want. To access the entity that the content is being rendered for, you can use the `useEntity` hook from `@backstage/plugin-catalog-react`. You can see a full list of APIs provided by the catalog React library in [the API reference](../../reference/plugin-catalog-react.md).
 
 For a more complete list of the different types of extensions that you can create for your plugin, see the [extension types](./03-extension-types.md) section.