Merge pull request #5553 from backstage/freben/composability-readmes

Minor composability etc docs changes

docs/features/kubernetes/installation.md

@@ -8,44 +8,36 @@ The Kubernetes feature is a plugin to Backstage, and it is exposed as a tab when
 viewing entities in the software catalog.
 
 If you haven't setup Backstage already, read the
-[Getting Started](../../getting-started/index.md).
+[Getting Started](../../getting-started/index.md) guide.
 
 ## Adding the Kubernetes frontend plugin
 
-The first step is to add the frontend Kubernetes plugin to your Backstage
-application. Navigate to your new Backstage application directory. And then to
+The first step is to add the Kubernetes frontend plugin to your Backstage
+application. Navigate to your new Backstage application directory, and then to
 your `packages/app` directory, and install the `@backstage/plugin-kubernetes`
 package.
 
 ```bash
-cd my-backstage-app/
+# From your Backstage root directory
 cd packages/app
 yarn add @backstage/plugin-kubernetes
 ```
 
 Once the package has been installed, you need to import the plugin in your app
-by adding the "Kubernetes" tab to the catalog entity page. In
-`packages/app/src/components/catalog/EntityPage.tsx`, you'll add a router to get
-to the tab, and add the tab itself.
-
-`EntityPage.tsx`:
+by adding the "Kubernetes" tab to the respective catalog pages.
 
 ```tsx
-import { Router as KubernetesRouter } from '@backstage/plugin-kubernetes';
+// In packages/app/src/components/catalog/EntityPage.tsx
+import { EntityKubernetesContent } from '@backstage/plugin-kubernetes';
 
-// ...
-
-const ServiceEntityPage = ({ entity }: { entity: Entity }) => (
-  <EntityPageLayout>
-    // ...
-    <EntityPageLayout.Content
-      path="/kubernetes/*"
-      title="Kubernetes"
-      element={<KubernetesRouter entity={entity} />}
-    />
-    // ...
-  </EntityPageLayout>
-);
+// You can add the tab to any number of pages, the service page is shown as an
+// example here
+const serviceEntityPage = (
+  <EntityLayout>
+    {/* other tabs... */}
+    <EntityLayout.Route path="/kubernetes" title="Kubernetes">
+      <EntityKubernetesContent />
+    </EntityLayout.Route>
 ```
 
 That's it! But now, we need the Kubernetes Backend plugin for the frontend to
@@ -57,17 +49,16 @@ Navigate to `packages/backend` of your Backstage app, and install the
 `@backstage/plugin-kubernetes-backend` package.
 
 ```bash
-cd my-backstage-app/
+# From your Backstage root directory
 cd packages/backend
 yarn add @backstage/plugin-kubernetes-backend
 ```
 
 Create a file called `kubernetes.ts` inside `packages/backend/src/plugins/` and
-add the following
-
-`kubernetes.ts`:
+add the following:
 
 ```typescript
+// In packages/backend/src/plugins/kubernetes.ts
 import { createRouter } from '@backstage/plugin-kubernetes-backend';
 import { PluginEnvironment } from '../types';
 
@@ -83,18 +74,15 @@ And import the plugin to `packages/backend/src/index.ts`. There are three lines
 of code you'll need to add, and they should be added near similar code in your
 existing Backstage backend.
 
-`index.ts`:
-
 ```typescript
+// In packages/backend/src/index.ts
 import kubernetes from './plugins/kubernetes';
-
 // ...
-
-const kubernetesEnv = useHotMemoize(module, () => createEnv('kubernetes'));
-
-// ...
-
-apiRouter.use('/kubernetes', await kubernetes(kubernetesEnv));
+async function main() {
+  // ...
+  const kubernetesEnv = useHotMemoize(module, () => createEnv('kubernetes'));
+  // ...
+  apiRouter.use('/kubernetes', await kubernetes(kubernetesEnv));
 ```
 
 That's it! The Kubernetes frontend and backend have now been added to your

docs/features/software-catalog/installation.md

@@ -18,6 +18,7 @@ The catalog frontend plugin should be installed in your `app` package, which is
 created as a part of `@backstage/create-app`. To install the package, run:
 
 ```bash
+# From your Backstage root directory
 cd packages/app
 yarn add @backstage/plugin-catalog
 ```
@@ -103,6 +104,7 @@ The catalog backend should be installed in your `backend` package, which is
 created as a part of `@backstage/create-app`. To install the package, run:
 
 ```bash
+# From your Backstage root directory
 cd packages/backend
 yarn add @backstage/plugin-catalog-backend
 ```

docs/features/software-templates/installation.md

@@ -20,6 +20,7 @@ The scaffolder frontend plugin should be installed in your `app` package, which
 is created as a part of `@backstage/create-app`. To install the package, run:
 
 ```bash
+# From your Backstage root directory
 cd packages/app
 yarn add @backstage/plugin-scaffolder
 ```
@@ -57,6 +58,7 @@ The scaffolder backend should be installed in your `backend` package, which is
 created as a part of `@backstage/create-app`. To install the package, run:
 
 ```bash
+# From your Backstage root directory
 cd packages/backend
 yarn add @backstage/plugin-scaffolder-backend
 ```

docs/features/techdocs/getting-started.md

@@ -22,7 +22,7 @@ Navigate to your new Backstage application directory. And then to your
 `packages/app` directory, and install the `@backstage/plugin-techdocs` package.
 
 ```bash
-cd my-backstage-app/
+# From your Backstage root directory
 cd packages/app
 yarn add @backstage/plugin-techdocs
 ```
@@ -54,7 +54,7 @@ Navigate to `packages/backend` of your Backstage app, and install the
 `@backstage/plugin-techdocs-backend` package.
 
 ```bash
-cd my-backstage-app/
+# From your Backstage root directory
 cd packages/backend
 yarn add @backstage/plugin-techdocs-backend
 ```

docs/plugins/integrating-plugin-into-service-catalog.md

@@ -1,7 +1,7 @@
 ---
 id: integrating-plugin-into-service-catalog
 title: Integrate into the Service Catalog
-description: Documentation on How to integrate plugin into service catalog
+description: How to integrate a plugin into service catalog
 ---
 
 > This is an advanced use case and currently is an experimental feature. Expect

docs/tutorials/switching-sqlite-postgres.md

@@ -17,11 +17,11 @@ switch between database backends.
 
 ## Install PostgreSQL
 
-First, swap out SQLite for PostgreSQL in your `backend` package:
+First, add PostgreSQL to your `backend` package:
 
 ```shell
+# From your Backstage root directory
 cd packages/backend
-yarn remove sqlite3
 yarn add pg
 ```
 
@@ -46,7 +46,6 @@ backend:
 +      #ssl: require # see https://www.postgresql.org/docs/current/libpq-ssl.html Table 33.1. SSL Mode Descriptions (e.g. require)
 +        #ca: # if you have a CA file and want to verify it you can uncomment this section
 +        #$file: <file-path>/ca/server.crt
-
 ```
 
 If you have an `app-config.local.yaml` for local development, a similar update

microsite/blog/2020-04-30-how-to-quickly-set-up-backstage.md

@@ -45,7 +45,7 @@ The only thing you need to do is to start the app:
 
 ```bash
 cd my-app
-yarn start
+yarn dev
 ```
 
 And you are good to go! 👍
@@ -101,18 +101,12 @@ We provide a collection of public Backstage plugins (look for packages with the
 Install in your app’s package folder (`<root>/packages/app`) with:
 
 ```bash
+# From your Backstage root directory
+cd packages/app
 yarn add @backstage/plugin-<plugin-name>
 ```
 
-Then add it to your app's `plugin.ts` file to import and register it:
-
-`<root>/packages/app/src/plugin.ts`:
-
-```js
-export { plugin as PluginName } from '@backstage/plugin-<plugin-name>';
-```
-
-A plugin registers its own `route` in the app — read the documentation for the specific plugin you are installing for more information on that.
+After that, you inject the plugin into the application where you want it to be exposed. Please read the documentation for the specific plugin you are installing for more information.
 
 ### Creating an internal plugin
 

packages/backend-common/README.md

@@ -8,6 +8,8 @@ error handling and similar.
 Add the library to your backend package:
 
 ```sh
+# From your Backstage root directory
+cd packages/backend
 yarn add @backstage/backend-common
 ```
 

packages/backend/src/plugins/kubernetes.ts

@@ -15,12 +15,11 @@
  */
 
 import { createRouter } from '@backstage/plugin-kubernetes-backend';
-import { Router } from 'express';
 import { PluginEnvironment } from '../types';
 
 export default async function createPlugin({
   logger,
   config,
-}: PluginEnvironment): Promise<Router> {
+}: PluginEnvironment) {
   return await createRouter({ logger, config });
 }

packages/cli/README.md

@@ -7,13 +7,13 @@ This package provides a CLI for developing Backstage plugins and apps.
 Install the package via npm or Yarn:
 
 ```sh
-$ npm install --save @backstage/cli
+npm install --save @backstage/cli
 ```
 
 or
 
 ```sh
-$ yarn add @backstage/cli
+yarn add @backstage/cli
 ```
 
 ## Development

packages/core-api/README.md

@@ -7,13 +7,13 @@ This package provides the core API used by Backstage plugins and apps.
 Do not install this package directly, it is reexported by `@backstage/core`. Install that instead:
 
 ```sh
-$ npm install --save @backstage/core
+npm install --save @backstage/core
 ```
 
 or
 
 ```sh
-$ yarn add @backstage/core
+yarn add @backstage/core
 ```
 
 ## Documentation

packages/core/README.md

@@ -7,13 +7,13 @@ This package provides the core API used by Backstage plugins and apps.
 Install the package via npm or Yarn:
 
 ```sh
-$ npm install --save @backstage/core
+npm install --save @backstage/core
 ```
 
 or
 
 ```sh
-$ yarn add @backstage/core
+yarn add @backstage/core
 ```
 
 ## Documentation

packages/dev-utils/README.md

@@ -9,13 +9,13 @@ This package provides utilities that help in developing plugins for Backstage, l
 Install the package via npm or Yarn:
 
 ```sh
-$ npm install --save-dev @backstage/dev-utils
+npm install --save-dev @backstage/dev-utils
 ```
 
 or
 
 ```sh
-$ yarn add -D @backstage/dev-utils
+yarn add -D @backstage/dev-utils
 ```
 
 ## Documentation

packages/test-utils/README.md

@@ -7,13 +7,13 @@ This package provides utilities that can be used to test plugins and apps for Ba
 Install the package via npm or Yarn:
 
 ```sh
-$ npm install --save-dev @backstage/test-utils
+npm install --save-dev @backstage/test-utils
 ```
 
 or
 
 ```sh
-$ yarn add -D @backstage/test-utils
+yarn add -D @backstage/test-utils
 ```
 
 ## Documentation

packages/theme/README.md

@@ -7,13 +7,13 @@ This package provides the extended Material UI Theme(s) that power Backstage.
 Install the package via npm or Yarn:
 
 ```sh
-$ npm install --save @backstage/theme
+npm install --save @backstage/theme
 ```
 
 or
 
 ```sh
-$ yarn add @backstage/theme
+yarn add @backstage/theme
 ```
 
 ## Documentation

plugins/api-docs/README.md

@@ -28,15 +28,15 @@ To link that a component provides or consumes an API, see the [`providesApis`](h
 1. Install the API docs plugin
 
 ```bash
-# packages/app
-
+# From your Backstage root directory
+cd packages/app
 yarn add @backstage/plugin-api-docs
 ```
 
 2. Add the `ApiExplorerPage` extension to the app:
 
 ```tsx
-// packages/app/src/App.tsx
+// In packages/app/src/App.tsx
 
 import { ApiExplorerPage } from '@backstage/plugin-api-docs';
 
@@ -56,7 +56,7 @@ import {
 } from '@backstage/plugin-api-docs';
 
 const apiPage = (
-  <EntityLayoutWrapper>
+  <EntityLayout>
     <EntityLayout.Route path="/" title="Overview">
       <Grid container spacing={3}>
         <Grid item md={6}>
@@ -80,7 +80,7 @@ const apiPage = (
         </Grid>
       </Grid>
     </EntityLayout.Route>
-  </EntityLayoutWrapper>
+  </EntityLayout>
 );
 
 // ...

plugins/app-backend/README.md

@@ -7,7 +7,9 @@ This backend plugin can be installed to serve static content of a Backstage app.
 Add both this package and your local frontend app package as dependencies to your backend, for example
 
 ```bash
-yarn add @backstage/plugin-app-backend example-app
+# From your Backstage root directory
+cd packages/backend
+yarn add @backstage/plugin-app-backend app
 ```
 
 By adding the app package as a dependency we ensure that it is built as part of the backend, and that it can be resolved at runtime.

plugins/bitrise/README.md

@@ -8,9 +8,9 @@ Welcome to the Bitrise plugin!
 ## Installation
 
 ```sh
-# The plugin must be added in the app package
-$ cd packages/app
-$ yarn add @backstage/plugin-bitrise
+# From your Backstage root directory
+cd packages/app
+yarn add @backstage/plugin-bitrise
 ```
 
 Bitrise Plugin exposes an entity tab component named `EntityBitriseContent`. You can include it in the
@@ -22,7 +22,7 @@ import { EntityBitriseContent } from '@backstage/plugin-bitrise';
 
 // Farther down at the website declaration
 const websiteEntityPage = (
-  <EntityLayoutWrapper>
+  <EntityLayout>
     {/* Place the following section where you want the tab to appear */}
     <EntityLayout.Route path="/bitrise" title="Bitrise">
       <EntityBitriseContent />

plugins/catalog-import/README.md

@@ -18,8 +18,8 @@ Some features are not yet available for all supported Git providers.
 1. Install the Catalog Import Plugin:
 
 ```bash
-# packages/app
-
+# From your Backstage root directory
+cd packages/app
 yarn add @backstage/plugin-catalog-import
 ```
 

plugins/circleci/README.md

@@ -7,34 +7,35 @@ Website: [https://circleci.com/](https://circleci.com/)
 
 ## Setup
 
-1. If you have standalone app (you didn't clone this repo), then do
+1. If you have a standalone app (you didn't clone this repo), then do
 
 ```bash
+# From your Backstage root directory
+cd packages/app
 yarn add @backstage/plugin-circleci
 ```
 
-2. Add the `EntityCircleCIContent` extension to the entity page in the app:
+2. Add the `EntityCircleCIContent` extension to the entity page in your app:
 
 ```tsx
-// packages/app/src/components/catalog/EntityPage.tsx
-import { EntityCircleCIContent } from '@backstage/plugin-circleci';
+// In packages/app/src/components/catalog/EntityPage.tsx
+import {
+  EntityCircleCIContent,
+  isCircleCIAvailable,
+} from '@backstage/plugin-circleci';
 
-// ...
-const serviceEntityPage = (
-  <EntityPageLayout>
-    ...
-    <EntityLayout.Route path="/circle-ci" title="Circle CI">
+// For example in the CI/CD section
+const cicdContent = (
+  <EntitySwitch>
+    <EntitySwitch.Case if={isCircleCIAvailable}>
       <EntityCircleCIContent />
-    </EntityLayout.Route>
-    ...
-  </EntityPageLayout>
-);
+    </EntitySwitch.Case>
 ```
 
 4. Add proxy config:
 
 ```yaml
-// app-config.yaml
+# In app-config.yaml
 proxy:
   '/circleci/api':
     target: https://circleci.com/api/v1.1
@@ -42,10 +43,11 @@ proxy:
       Circle-Token: ${CIRCLECI_AUTH_TOKEN}
 ```
 
-5. Get and provide `CIRCLECI_AUTH_TOKEN` as env variable (https://circleci.com/docs/api/#add-an-api-token)
-6. Add `circleci.com/project-slug` annotation to your catalog-info.yaml file in format <git-provider>/<owner>/<project> (https://backstage.io/docs/architecture-decisions/adrs-adr002#format)
+5. Get and provide a `CIRCLECI_AUTH_TOKEN` as an environment variable (see the [CircleCI docs](https://circleci.com/docs/api/#add-an-api-token)).
+6. Add a `circleci.com/project-slug` annotation to your respective `catalog-info.yaml` files, on the format <git-provider>/<owner>/<project> (https://backstage.io/docs/architecture-decisions/adrs-adr002#format).
 
 ```yaml
+# Example catalog-info.yaml entity definition file
 apiVersion: backstage.io/v1alpha1
 kind: Component
 metadata:

plugins/cost-insights/README.md

@@ -16,6 +16,8 @@ Learn more with the Backstage blog post [New Cost Insights plugin: The engineer'
 ## Install
 
 ```bash
+# From your Backstage root directory
+cd packages/app
 yarn add @backstage/plugin-cost-insights
 ```
 

plugins/cost-insights/contrib/aws-cost-explorer-api.md

@@ -33,6 +33,8 @@ Cost Explorer permission policy:
 Install the AWS Cost Explorer SDK. The AWS docs recommend using the SDK over making calls to the API directly as it simplifies authentication and provides direct access to commands.
 
 ```bash
+# From your Backstage root directory
+cd packages/app
 yarn add @aws-sdk/client-cost-explorer
 ```
 

plugins/fossa/README.md

@@ -9,8 +9,8 @@ The FOSSA Plugin displays code statistics from [FOSSA](https://fossa.com/).
 1. Install the FOSSA Plugin:
 
 ```bash
-# packages/app
-
+# From your Backstage root directory
+cd packages/app
 yarn add @backstage/plugin-fossa
 ```
 

plugins/github-actions/README.md

@@ -11,15 +11,15 @@ TBD
 ### Generic Requirements
 
 1. Provide OAuth credentials:
-   1. [Create an OAuth App](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/) with callback URL set to `http://localhost:7000/api/auth/github`.
-   2. Take Client ID and Client Secret from the newly created app's settings page and put them into `AUTH_GITHUB_CLIENT_ID` and `AUTH_GITHUB_CLIENT_SECRET` env variables.
+   1. [Create an OAuth App](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/) with the callback URL set to `http://localhost:7000/api/auth/github`.
+   2. Take the Client ID and Client Secret from the newly created app's settings page and put them into `AUTH_GITHUB_CLIENT_ID` and `AUTH_GITHUB_CLIENT_SECRET` environment variables.
 2. Annotate your component with a correct GitHub Actions repository and owner:
 
    The annotation key is `github.com/project-slug`.
 
    Example:
 
-   ```
+   ```yaml
    apiVersion: backstage.io/v1alpha1
    kind: Component
    metadata:
@@ -38,6 +38,7 @@ TBD
 1. Install the plugin dependency in your Backstage app package:
 
 ```bash
+# From your Backstage root directory
 cd packages/app
 yarn add @backstage/plugin-github-actions
 ```
@@ -45,22 +46,24 @@ yarn add @backstage/plugin-github-actions
 2. Add to the app `EntityPage` component:
 
 ```tsx
-// packages/app/src/components/catalog/EntityPage.tsx
-import { EntityGithubActionsContent } from '@backstage/plugin-github-actions';
+// In packages/app/src/components/catalog/EntityPage.tsx
+import {
+  EntityGithubActionsContent,
+  isGithubActionsAvailable,
+} from '@backstage/plugin-github-actions';
 
-// ...
+// You can add the tab to any number of pages, the service page is shown as an
+// example here
 const serviceEntityPage = (
-  <EntityPageLayout>
-    ...
+  <EntityLayout>
+    {/* other tabs... */}
     <EntityLayout.Route path="/github-actions" title="GitHub Actions">
       <EntityGithubActionsContent />
     </EntityLayout.Route>
-    ...
-  </EntityPageLayout>
-);
 ```
 
-2. Run the app with `yarn start` and the backend with `yarn --cwd packages/backend start`, navigate to `/github-actions/`.
+3. Run the app with `yarn start` and the backend with `yarn start-backend`.
+   Then navigate to `/github-actions/` under any entity.
 
 ## Features
 

plugins/github-deployments/README.md

@@ -13,8 +13,8 @@ The GitHub Deployments Plugin displays recent deployments from GitHub.
 1. Install the GitHub Deployments Plugin.
 
 ```bash
-# packages/app
-
+# From your Backstage root directory
+cd packages/app
 yarn add @backstage/plugin-github-deployments
 ```
 

plugins/graphiql/README.md

@@ -12,6 +12,7 @@ By exposing GraphiQL as a plugin instead of a standalone app, it's possible to p
 Start out by installing the plugin in your Backstage app:
 
 ```bash
+# From your Backstage root directory
 cd packages/app
 yarn add @backstage/plugin-graphiql
 ```

plugins/jenkins/README.md

@@ -11,25 +11,25 @@ Website: [https://jenkins.io/](https://jenkins.io/)
 1. If you have a standalone app (you didn't clone this repo), then do
 
 ```bash
+# From your Backstage root directory
+cd packages/app
 yarn add @backstage/plugin-jenkins
 ```
 
 2. Add the `EntityJenkinsContent` extension to the entity page in the app:
 
 ```tsx
-// packages/app/src/components/catalog/EntityPage.tsx
-import { EntityJenkinsContent } from '@backstage/plugin-circleci';
+// In packages/app/src/components/catalog/EntityPage.tsx
+import { EntityJenkinsContent } from '@backstage/plugin-jenkins';
 
-// ...
+// You can add the tab to any number of pages, the service page is shown as an
+// example here
 const serviceEntityPage = (
-  <EntityPageLayout>
-    ...
+  <EntityLayout>
+    {/* other tabs... */}
     <EntityLayout.Route path="/jenkins" title="Jenkins">
       <EntityJenkinsContent />
     </EntityLayout.Route>
-    ...
-  </EntityPageLayout>
-);
 ```
 
 3. Add proxy configuration to `app-config.yaml`
@@ -43,14 +43,18 @@ proxy:
       Authorization: Basic ${JENKINS_BASIC_AUTH_HEADER}
 ```
 
-4. Add an environment variable which contains the Jenkins credentials, (note: use an API token not your password). Here user is the name of the user created in Jenkins.
+4. Add an environment variable which contains the Jenkins credentials (NOTE:
+   use an API token, not your password). Here `user` is the name of the user
+   created in Jenkins.
 
 ```shell
 export JENKINS_BASIC_AUTH_HEADER=$(echo -n user:api-token | base64)
 ```
 
-5. Run app with `yarn start`
-6. Add the Jenkins folder annotation to your `catalog-info.yaml`, (note: currently this plugin only supports folders and Git SCM)
+5. Run the app with `yarn start`
+
+6. Add the Jenkins folder annotation to your `catalog-info.yaml`, (NOTE:
+   currently this plugin only supports folders and Git SCM)
 
 ```yaml
 apiVersion: backstage.io/v1alpha1
@@ -68,11 +72,11 @@ spec:
 
 7. Register your component
 
-8. Click the component in the catalog you should now see Jenkins builds, and a last build result for your master build.
+8. Click the component in the catalog. You should now see Jenkins builds, and a
+   last build result for your master build.
 
-Note:
-
-If you are not using environment variable then you can directly type API token in app-config.yaml
+Note: If you are not using environment variables, you can directly type the API
+token into `app-config.yaml`.
 
 ```yaml
 proxy:
@@ -83,7 +87,8 @@ proxy:
       Authorization: Basic YWRtaW46MTFlYzI1NmU0Mzg1MDFjM2Y1Yzc2Yjc1MWE3ZTQ3YWY4Mw==
 ```
 
-YWRtaW46MTFlYzI1NmU0Mzg1MDFjM2Y1Yzc2Yjc1MWE3ZTQ3YWY4Mw== is the base64 of user and it's API token e.g. admin:11ec256e438501c3f5c76b751a7e47af83
+The string starting with `YWR...` is the base64 encoding of the user and their
+API token, e.g. `admin:11ec256e438501c3f5c76b751a7e47af83`.
 
 ## Features
 
@@ -94,4 +99,5 @@ YWRtaW46MTFlYzI1NmU0Mzg1MDFjM2Y1Yzc2Yjc1MWE3ZTQ3YWY4Mw== is the base64 of user a
 ## Limitations
 
 - Only works with organization folder projects backed by GitHub
-- No pagination support currently, limited to 50 projects - don't run this on a Jenkins with lots of builds
+- No pagination support currently, limited to 50 projects - don't run this on a
+  Jenkins instance with lots of builds

plugins/kafka-backend/README.md

@@ -1,6 +1,7 @@
 # Kafka Backend
 
-This is the backend part of the Kafka plugin. It responds to Kafka requests from the frontend.
+This is the backend part of the Kafka plugin. It responds to Kafka requests
+from the frontend.
 
 ## Configuration
 
@@ -16,7 +17,9 @@ A list of the brokers' host names and ports to connect to.
 
 ### `ssl` (optional)
 
-Configure TLS connection to the Kafka cluster. The options are passed directly to [tls.connect] and used to create the TLS secure context. Normally these would include `key` and `cert`.
+Configure TLS connection to the Kafka cluster. The options are passed directly
+to [tls.connect] and used to create the TLS secure context. Normally these
+would include `key` and `cert`.
 
 Example:
 
@@ -39,7 +42,7 @@ kafka:
   clusters:
     - name: prod
       brokers:
-        - my-cluser:9092
+        - my-cluster:9092
       ssl: true
       sasl:
         mechanism: plain # or 'scram-sha-256' or 'scram-sha-512'

plugins/kafka/README.md

@@ -7,7 +7,9 @@
 1. Run:
 
 ```bash
-yarn add @backstage/plugin-kafka @backstage/plugin-kafka-backend
+# From your Backstage root directory
+yarn --cwd packages/app add @backstage/plugin-kafka
+yarn --cwd packages/backend add @backstage/plugin-kafka-backend
 ```
 
 2. Add the plugin backend:
@@ -29,41 +31,31 @@ export default async function createPlugin({
 And then add to `packages/backend/src/index.ts`:
 
 ```js
-// ...
+// In packages/backend/src/index.ts
 import kafka from './plugins/kafka';
 // ...
 async function main() {
   // ...
   const kafkaEnv = useHotMemoize(module, () => createEnv('kafka'));
   // ...
-
-  const apiRouter = Router();
-  // ...
   apiRouter.use('/kafka', await kafka(kafkaEnv));
-  // ...
 ```
 
-3. Add the plugin frontend to `packages/app/src/plugin.ts`:
-
-```js
-export { plugin as Kafka } from '@backstage/plugin-kafka';
-```
-
-4. Register the plugin frontend router in `packages/app/src/components/catalog/EntityPage.tsx`:
+3. Add the plugin as a tab to your service entities:
 
 ```jsx
-import { Router as KafkaRouter } from '@backstage/plugin-kafka';
+// In packages/app/src/components/catalog/EntityPage.tsx
+import { EntityKafkaContent } from '@backstage/plugin-kafka';
 
-// Then, somewhere inside <EntityPageLayout>
-
-<EntityPageLayout.Content
-  path="/kafka/*"
-  title="Kafka"
-  element={<KafkaRouter entity={entity} />}
-/>;
+const serviceEntityPage = (
+  <EntityLayout>
+    {/* other tabs... */}
+    <EntityLayout.Route path="/kafka" title="Kafka">
+      <EntityKafkaContent />
+    </EntityLayout.Route>
 ```
 
-5. Add broker configs for the backend in your `app-config.yaml` (see
+4. Add broker configs for the backend in your `app-config.yaml` (see
    [kafka-backend](https://github.com/backstage/backstage/blob/master/plugins/kafka-backend/README.md)
    for more options):
 
@@ -76,7 +68,7 @@ kafka:
         - localhost:9092
 ```
 
-6. Add `kafka.apache.org/consumer-groups` annotation to your services:
+5. Add the `kafka.apache.org/consumer-groups` annotation to your services:
 
 ```yaml
 apiVersion: backstage.io/v1alpha1

plugins/lighthouse/README.md

@@ -28,20 +28,21 @@ _It's likely you will need to [enable CORS](https://developer.mozilla.org/en-US/
 When you have an instance running that Backstage can hook into, first install the plugin into your app:
 
 ```sh
-$ yarn add @backstage/plugin-lighthouse
+# From your Backstage root directory
+cd packages/app
+yarn add @backstage/plugin-lighthouse
 ```
 
 Modify your app routes in `App.tsx` to include the `LighthousePage` component exported from the plugin, for example:
 
 ```tsx
-// At the top imports
+// In packages/app/src/App.tsx
 import { LighthousePage } from '@backstage/plugin-lighthouse';
 
-<FlatRoutes>
-  // ...
-  <Route path="/lighthouse" element={<LighthousePage />} />
-  // ...
-</FlatRoutes>;
+const routes = (
+  <FlatRoutes>
+    {/* ...other routes */}
+    <Route path="/lighthouse" element={<LighthousePage />} />
 ```
 
 Then configure the `lighthouse-audit-service` URL in your [`app-config.yaml`](https://github.com/backstage/backstage/blob/master/app-config.yaml).
@@ -63,55 +64,45 @@ kind: Component
 metadata:
   # ...
   annotations:
-    # ...
     lighthouse.com/website-url: # A single website url e.g. https://backstage.io/
 ```
 
 > NOTE: The plugin only supports one website URL per component at this time.
 
-Add a **Lighthouse tab** to the EntityPage:
+Add a Lighthouse tab to the entity page:
 
 ```tsx
-// packages/app/src/components/catalog/EntityPage.tsx
-import { EmbeddedRouter as LighthouseRouter } from '@backstage/plugin-lighthouse';
+// In packages/app/src/components/catalog/EntityPage.tsx
+import { EntityLighthouseContent } from '@backstage/plugin-lighthouse';
 
-// ...
-const WebsiteEntityPage = ({ entity }: { entity: Entity }) => (
-  <EntityPageLayout>
-    // ...
-    <EntityPageLayout.Content
-      path="/lighthouse/*"
-      title="Lighthouse"
-      element={<LighthouseRouter entity={entity} />}
-    />
-  </EntityPageLayout>
-);
+const websiteEntityPage = (
+  <EntityLayout>
+    {/* other tabs... */}
+    <EntityLayout.Route path="/lighthouse" title="Lighthouse">
+      <EntityLighthouseContent />
+    </EntityLayout.Route>
 ```
 
-> NOTE: The embedded router renders page content without a header section allowing it to be rendered within a
-> catalog plugin page.
+> NOTE: The embedded router renders page content without a header section
+> allowing it to be rendered within a catalog plugin page.
 
 Add a **Lighthouse card** to the overview tab on the EntityPage:
 
 ```tsx
-// packages/app/src/components/catalog/EntityPage.tsx
+// In packages/app/src/components/catalog/EntityPage.tsx
 import {
-  LastLighthouseAuditCard,
-  isPluginApplicableToEntity as isLighthouseAvailable,
+  EntityLastLighthouseAuditCard,
+  isLighthouseAvailable,
 } from '@backstage/plugin-lighthouse';
 
-// ...
-
-const OverviewContent = ({ entity }: { entity: Entity }) => (
-  <Grid container spacing={3}>
-    // ...
-    {isLighthouseAvailable(entity) && (
-      <Grid item sm={4}>
-        <LastLighthouseAuditCard />
-      </Grid>
-    )}
-  </Grid>
-);
+const overviewContent = (
+  <Grid container spacing={3} alignItems="stretch">
+    {/* ...other content */}
+    <EntitySwitch>
+      <EntitySwitch.Case if={isLighthouseAvailable}>
+        <Grid item md={6}>
+          <EntityLastLighthouseAuditCard />
+        </Grid>
+      </EntitySwitch.Case>
+    </EntitySwitch>
 ```
-
-Link Lighthouse

plugins/lighthouse/src/components/Intro/index.tsx

@@ -46,7 +46,8 @@ with the environment variable \`LAS_CORS\` set to \`true\`._
 When you have an instance running that Backstage can hook into, first install the plugin into your app:
 
 \`\`\`sh
-$ yarn add @backstage/plugin-lighthouse
+cd packages/app
+yarn add @backstage/plugin-lighthouse
 \`\`\`
 
 Modify your app routes in \`App.tsx\` to include the \`LighthousePage\` component exported from the plugin, for example:

plugins/pagerduty/README.md

@@ -19,6 +19,8 @@ This plugin provides:
 Install the plugin:
 
 ```bash
+# From your Backstage root directory
+cd packages/app
 yarn add @backstage/plugin-pagerduty
 ```
 

plugins/register-component/README.md

@@ -19,6 +19,7 @@ When installed it is accessible on [localhost:3000/register-component](localhost
 1. Install plugin and its dependency `plugin-catalog`
 
 ```bash
+# From your Backstage root directory
 cd packages/app
 yarn add @backstage/plugin-register-component
 ```

plugins/rollbar/README.md

@@ -9,25 +9,23 @@ Website: [https://rollbar.com/](https://rollbar.com/)
 2. If you have standalone app (you didn't clone this repo), then do
 
 ```bash
+# From your Backstage root directory
+cd packages/app
 yarn add @backstage/plugin-rollbar
 ```
 
 3. Add to the app `EntityPage` component:
 
 ```tsx
-// packages/app/src/components/catalog/EntityPage.tsx
+// In packages/app/src/components/catalog/EntityPage.tsx
 import { EntityRollbarContent } from '@backstage/plugin-rollbar';
 
-// ...
 const serviceEntityPage = (
-  <EntityPageLayout>
-    ...
+  <EntityLayout>
+    {/* other tabs... */}
     <EntityLayout.Route path="/rollbar" title="Rollbar">
       <EntityRollbarContent />
     </EntityLayout.Route>
-    ...
-  </EntityPageLayout>
-);
 ```
 
 4. Setup the `app-config.yaml` and account token environment variable

plugins/sentry/README.md

@@ -9,8 +9,8 @@ The Sentry Plugin displays issues from [Sentry](https://sentry.io).
 1. Install the Sentry Plugin:
 
 ```bash
-# packages/app
-
+# From your Backstage root directory
+cd packages/app
 yarn add @backstage/plugin-sentry
 ```
 

plugins/sonarqube/README.md

@@ -9,7 +9,8 @@ The SonarQube Plugin displays code statistics from [SonarCloud](https://sonarclo
 1. Install the SonarQube Plugin:
 
 ```bash
-# packages/app
+# From your Backstage root directory
+cd packages/app
 yarn add @backstage/plugin-sonarqube
 ```
 

plugins/splunk-on-call/README.md

@@ -20,6 +20,8 @@ This plugin provides:
 Install the plugin:
 
 ```bash
+# From your Backstage root directory
+cd packages/app
 yarn add @backstage/plugin-splunk-on-call
 ```
 

plugins/tech-radar/README.md

@@ -26,6 +26,7 @@ The Tech Radar can be used in two ways:
 For either simple or advanced installations, you'll need to add the dependency using Yarn:
 
 ```sh
+# From your Backstage root directory
 cd packages/app
 yarn add @backstage/plugin-tech-radar
 ```
@@ -35,12 +36,12 @@ yarn add @backstage/plugin-tech-radar
 Modify your app routes to include the Router component exported from the tech radar, for example:
 
 ```tsx
-// in packages/app/src/App.tsx
+// In packages/app/src/App.tsx
 import { TechRadarPage } from '@backstage/plugin-tech-radar';
 
 const routes = (
   <FlatRoutes>
-    {/* ... */}
+    {/* ...other routes */}
     <Route
       path="/tech-radar"
       element={<TechRadarPage width={1500} height={800} />}

plugins/techdocs-backend/examples/documented-component/docs/code/code-sample.md

@@ -5,19 +5,19 @@ This page provides some sample code which may be used in your example component.
 This code uses TypeScript, and the Markdown code fence to wrap the code.
 
 ```typescript
-const DefaultEntityPage = ({ entity }: { entity: Entity }) => (
-  <EntityPageLayout>
-    <EntityPageLayout.Content
-      path="/*"
-      title="Overview"
-      element={<ComponentOverviewContent entity={entity} />}
-    />
-    <EntityPageLayout.Content
-      path="/docs/*"
-      title="Docs"
-      element={<DocsRouter entity={entity} />}
-    />
-  </EntityPageLayout>
+const serviceEntityPage = (
+  <EntityLayout>
+    <EntityLayout.Route path="/" title="Overview">
+      <Grid container spacing={3} alignItems="stretch">
+        <Grid item md={6}>
+          <EntityAboutCard variant="gridItem" />
+        </Grid>
+      </Grid>
+    </EntityLayout.Route>
+    <EntityLayout.Route path="/docs" title="Docs">
+      <EntityTechdocsContent />
+    </EntityLayout.Route>
+  </EntityLayout>
 );
 ```