Merge branch 'master' into k8s-plugin

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

.changeset/angry-bobcats-sit.md

@@ -0,0 +1,5 @@
+---
+'@backstage/backend-common': patch
+---
+
+The `subscribe` method on the `Config` returned by `loadBackendConfig` is now forwarded through `getConfig` and `getOptionalConfig`.

.changeset/angry-spies-warn.md

@@ -1,5 +0,0 @@
----
-'@backstage/techdocs-common': patch
----
-
-Fix validation of mkdocs.yml docs_dir

.changeset/beige-moose-look.md

@@ -0,0 +1,5 @@
+---
+'@backstage/cli': patch
+---
+
+Only serve static assets if there is a public folder during `app:serve` and `plugin:serve`. This fixes a common bug that would break `plugin:serve` with an `EBUSY` error.

.changeset/brave-shoes-push.md

@@ -0,0 +1,40 @@
+---
+'@backstage/create-app': patch
+---
+
+Added the default `ScmAuth` implementation to the app.
+
+To apply this change to an existing app, head to `packages/app/apis.ts`, import `ScmAuth` from `@backstage/integration-react`, and add a `ScmAuth.createDefaultApiFactory()` to your list of APIs:
+
+```diff
+ import {
+   ScmIntegrationsApi,
+   scmIntegrationsApiRef,
++   ScmAuth,
+ } from '@backstage/integration-react';
+
+ export const apis: AnyApiFactory[] = [
+...
++  ScmAuth.createDefaultApiFactory(),
+...
+ ];
+```
+
+If you have integrations towards SCM providers other than the default ones (github.com, gitlab.com, etc.), you will want to create a custom `ScmAuth` factory instead, for example like this:
+
+```ts
+createApiFactory({
+  api: scmAuthApiRef,
+  deps: {
+    gheAuthApi: gheAuthApiRef,
+    githubAuthApi: githubAuthApiRef,
+  },
+  factory: ({ githubAuthApi, gheAuthApi }) =>
+    ScmAuth.merge(
+      ScmAuth.forGithub(githubAuthApi),
+      ScmAuth.forGithub(gheAuthApi, {
+        host: 'ghe.example.com',
+      }),
+    ),
+});
+```

.changeset/breezy-foxes-wonder.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-backend': patch
+---
+
+When issuing a `full` update from an entity provider, entities with updates are now properly persisted.

.changeset/calm-buckets-relax.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-azure-devops-backend': patch
+---
+
+Marked all configuration values as required in the schema.

.changeset/clever-pigs-drum.md

@@ -1,5 +0,0 @@
----
-'@backstage/catalog-client': patch
----
-
-Export `CatalogRequestOptions` type

.changeset/cold-bags-admire.md

@@ -0,0 +1,6 @@
+---
+'@backstage/plugin-techdocs': patch
+'@backstage/plugin-user-settings': patch
+---
+
+Add "data-testid" for e2e tests and fix techdocs entity not found error.

.changeset/curly-months-count.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-backend': patch
+---
+
+Fixed a bug where internal references within the catalog were broken when new entities where added through entity providers, such as registering a new location or adding one in configuration. These broken references then caused some entities to be incorrectly marked as orphaned and prevented refresh from working properly.

.changeset/eighty-jokes-roll.md

@@ -1,5 +0,0 @@
----
-'@backstage/plugin-auth-backend': patch
----
-
-TokenIssuer is now exported so it may be used by auth providers that are not bundled with Backstage

.changeset/fifty-panthers-play.md

@@ -1,5 +0,0 @@
----
-'@backstage/plugin-jenkins-backend': patch
----
-
-Update `@backstage/backend-common` to `^0.8.6`

.changeset/forty-singers-look.md

@@ -1,5 +0,0 @@
----
-'@backstage/core-app-api': patch
----
-
-Fix a bug in `FlatRoutes` that prevented outlets from working with the root route, as well as matching root routes too broadly.

.changeset/funny-moose-tie.md

@@ -1,5 +0,0 @@
----
-'@backstage/plugin-catalog-import': patch
----
-
-Fix heading that wrongly implied catalog-import supports entity discovery for multiple integrations.

.changeset/fuzzy-pots-whisper.md

@@ -1,15 +0,0 @@
----
-'@backstage/backend-common': patch
----
-
-It's possible to customize the request logging handler when building the service. For example in your `backend`
-
-```
-  const service = createServiceBuilder(module)
-    .loadConfig(config)
-    .setRequestLoggingHandler((logger?: Logger): RequestHandler => {
-      const actualLogger = (logger || getRootLogger()).child({
-        type: 'incomingRequest',
-      });
-      return expressWinston.logger({ ...
-```

.changeset/good-cars-confess.md

@@ -0,0 +1,5 @@
+---
+'@backstage/cli': patch
+---
+
+Configuration schema is now also collected from the root `package.json` if it exists.

.changeset/great-humans-return.md

@@ -0,0 +1,5 @@
+---
+'@backstage/core-app-api': patch
+---
+
+Enables late registration of plugins into the application by updating ApiHolder when additional plugins have been added in.

.changeset/great-rabbits-juggle.md

@@ -0,0 +1,36 @@
+---
+'@backstage/plugin-catalog-import': minor
+---
+
+Switched to using the `ScmAuthApi` for authentication rather than GitHub auth. If you are instantiating your `CatalogImportClient` manually you now need to pass in an instance of `ScmAuthApi` instead.
+
+Also be sure to register the `scmAuthApiRef` from the `@backstage/integration-react` in your app:
+
+```ts
+import { ScmAuth } from '@backstage/integration-react';
+
+// in packages/app/apis.ts
+
+const apis = [
+// ... other APIs
+
+ScmAuth.createDefaultApiFactory();
+
+// OR
+
+createApiFactory({
+  api: scmAuthApiRef,
+  deps: {
+    gheAuthApi: gheAuthApiRef,
+    githubAuthApi: githubAuthApiRef,
+  },
+  factory: ({ githubAuthApi, gheAuthApi }) =>
+    ScmAuth.merge(
+      ScmAuth.forGithub(githubAuthApi),
+      ScmAuth.forGithub(gheAuthApi, {
+        host: 'ghe.example.com',
+      }),
+    ),
+});
+]
+```

.changeset/green-lies-hammer.md

@@ -1,8 +0,0 @@
----
-'@backstage/core-components': patch
-'@backstage/test-utils': patch
-'@backstage/plugin-api-docs': patch
-'@backstage/plugin-catalog': patch
----
-
-Updated the layout of catalog and API index pages to handle smaller screen sizes. This adds responsive wrappers to the entity tables, and switches filters to a drawer when width-constrained. If you have created a custom catalog or API index page, you will need to update the page structure to match the updated [catalog customization](https://backstage.io/docs/features/software-catalog/catalog-customization) documentation.

.changeset/healthy-cycles-exercise.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-techdocs': patch
+---
+
+Fixed the URL for the "Click to copy documentation link to clipboard" action

.changeset/heavy-rabbits-melt.md

@@ -0,0 +1,5 @@
+---
+'@backstage/cli': patch
+---
+
+The `create-plugin` command now prefers dependency versions ranges that are already in the lockfile.

.changeset/honest-ghosts-listen.md

@@ -1,5 +0,0 @@
----
-'@backstage/cli': patch
----
-
-chore: bump `eslint` to `7.30.0`

.changeset/hot-years-return.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-backend-module-msgraph': patch
+---
+
+Bumped `@microsoft/microsoft-graph-types` to v2

.changeset/khaki-hotels-doubt.md

@@ -0,0 +1,5 @@
+---
+'@backstage/integration': patch
+---
+
+Support selective GitHub app installation for GHE

.changeset/khaki-rivers-repeat.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-badges': patch
+---
+
+Added details on how to setup the Badges plugin

.changeset/large-files-beg.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-cost-insights': patch
+---
+
+Added optional currencies config to allow overriding the default currencies.

.changeset/late-kiwis-double.md

@@ -0,0 +1,5 @@
+---
+'@backstage/config-loader': patch
+---
+
+Add option to collect configuration schemas from explicit package paths in addition to by package name.

.changeset/late-news-chew.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-tech-radar': patch
+---
+
+Added `SearchBar` to allow filtering and a scroll bar to display hidden tech

.changeset/little-cobras-think.md

@@ -0,0 +1,5 @@
+---
+'@backstage/cli': patch
+---
+
+Improved ´plugin:diff´ check for the `package.json` `"files"` field.

.changeset/mighty-books-decide.md

@@ -1,7 +0,0 @@
----
-'@backstage/plugin-git-release-manager': minor
----
-
-Enable users to add custom features
-
-Add more metadata to success callbacks

.changeset/mighty-students-itch.md

@@ -0,0 +1,5 @@
+---
+'@backstage/backend-common': patch
+---
+
+Fix an issue where filtering in search doesn't work correctly for Bitbucket.

.changeset/nasty-worms-approve.md

@@ -1,5 +0,0 @@
----
-'@backstage/plugin-catalog': patch
----
-
-Export `CatalogClientWrapper` class

.changeset/nervous-months-teach.md

@@ -0,0 +1,5 @@
+---
+'@backstage/config-loader': patch
+---
+
+Allow collection of configuration schemas from multiple versions of the same package.

.changeset/ninety-games-lie.md

@@ -0,0 +1,5 @@
+---
+'@backstage/core-plugin-api': patch
+---
+
+Improve compatibility between different versions by defining the route reference type using a string key rather than a unique symbol. This change only applies to type checking and has no effect on the runtime value, where we still use the symbol.

.changeset/pink-windows-suffer.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-techdocs': patch
+---
+
+Added a check for the TechDocs annotation on the entity

.changeset/plenty-feet-pay.md

@@ -0,0 +1,5 @@
+---
+'@backstage/core-components': patch
+---
+
+Stop forcing `target="_blank"` in the `SupportButton` but instead use the default logic of the `Link` component, that opens external targets in a new window and relative targets in the same window.

.changeset/poor-jars-sniff.md

@@ -1,15 +0,0 @@
----
-'@backstage/core-components': patch
-'@backstage/create-app': patch
-'@backstage/plugin-catalog': patch
-'@backstage/plugin-techdocs': patch
----
-
-Improve the responsiveness of the EntityPage UI. With this the Header component should scale with the screen size & wrapping should not cause overflowing/blocking of links. Additionally enforce the Pages using the Grid Layout to use it across all screen sizes & to wrap as intended.
-
-To benefit from the improved responsive layout, the `EntityPage` in existing Backstage applications should be updated to set the `xs` column size on each grid item in the page, as this does not default. For example:
-
-```diff
--  <Grid item md={6}>
-+  <Grid item xs={12} md={6}>
-```

.changeset/pretty-feet-explode.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-auth-backend': patch
+---
+
+Allow users to override callback url of GitHub provider

.changeset/proud-carrots-prove.md

@@ -0,0 +1,5 @@
+---
+'@backstage/cli': patch
+---
+
+Fix duplication checks to stop looking for the old core packages, and to allow some explicitly

.changeset/purple-scissors-allow.md

@@ -0,0 +1,89 @@
+---
+'@backstage/integration-react': patch
+---
+
+Added `ScmAuthApi` along with the implementation `ScmAuth`. The `ScmAuthApi` provides methods for client-side authentication towards multiple different source code management services simultaneously.
+
+When requesting credentials you supply a URL along with the same options as the other `OAuthApi`s, and optionally a request for additional high-level scopes.
+
+For example like this:
+
+```ts
+const { token } = await scmAuthApi.getCredentials({
+  url: 'https://ghe.example.com/backstage/backstage',
+  additionalScope: {
+    repoWrite: true,
+  },
+});
+```
+
+The instantiation of the API can either be done with a default factory that adds support for the public providers (github.com, gitlab.com, etc.):
+
+```ts
+// in packages/app/apis.ts
+ScmAuth.createDefaultApiFactory();
+```
+
+Or with a more custom setup that can add support for additional providers, for example like this:
+
+```ts
+createApiFactory({
+  api: scmAuthApiRef,
+  deps: {
+    gheAuthApi: gheAuthApiRef,
+    githubAuthApi: githubAuthApiRef,
+  },
+  factory: ({ githubAuthApi, gheAuthApi }) =>
+    ScmAuth.merge(
+      ScmAuth.forGithub(githubAuthApi),
+      ScmAuth.forGithub(gheAuthApi, {
+        host: 'ghe.example.com',
+      }),
+    ),
+});
+```
+
+The additional `gheAuthApiRef` utility API can be defined either inside the app itself if it's only used for this purpose, for inside an internal common package for APIs, such as `@internal/apis`:
+
+```ts
+const gheAuthApiRef: ApiRef<OAuthApi & ProfileInfoApi & SessionApi> =
+  createApiRef({
+    id: 'internal.auth.ghe',
+  });
+```
+
+And then implemented using the `GithubAuth` class from `@backstage/core-app-api`:
+
+```ts
+createApiFactory({
+  api: githubAuthApiRef,
+  deps: {
+    discoveryApi: discoveryApiRef,
+    oauthRequestApi: oauthRequestApiRef,
+    configApi: configApiRef,
+  },
+  factory: ({ discoveryApi, oauthRequestApi, configApi }) =>
+    GithubAuth.create({
+      provider: {
+        id: 'ghe',
+        icon: ...,
+        title: 'GHE'
+      },
+      discoveryApi,
+      oauthRequestApi,
+      defaultScopes: ['read:user'],
+      environment: configApi.getOptionalString('auth.environment'),
+    }),
+})
+```
+
+Finally you also need to add and configure another GitHub provider to the `auth-backend` using the provider ID `ghe`:
+
+```ts
+// Add the following options to `createRouter` in packages/backend/src/plugins/auth.ts
+providerFactories: {
+  ghe: createGithubProvider(),
+},
+```
+
+Other providers follow the same steps, but you will want to use the appropriate auth API implementation in the frontend, such as for example `GitlabAuth`.

.changeset/red-hats-walk.md

@@ -0,0 +1,8 @@
+---
+'@backstage/core-components': minor
+---
+
+Checkbox tree filters are no longer available in the Table component:
+
+- Deleted the `CheckboxTree` component
+- Removed the filter type `'checkbox-tree'` from the `TableFilter` types.

.changeset/rotten-dryers-bathe.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-kubernetes': patch
+---
+
+Exported `KubernetesApi`, `kubernetesApiRef`, and `KubernetesAuthProvidersApi`.

.changeset/seven-bulldogs-grin.md

@@ -0,0 +1,11 @@
+---
+'@backstage/plugin-catalog-backend': minor
+---
+
+Introduced a new `CatalogProcessorCache` that is available to catalog processors. It allows arbitrary values to be saved that will then be visible during the next run. The cache is scoped to each individual processor and entity, but is shared across processing steps in a single processor.
+
+The cache is available as a new argument to each of the processing steps, except for `validateEntityKind` and `handleError`.
+
+This also introduces an optional `getProcessorName` to the `CatalogProcessor` interface, which is used to provide a stable identifier for the processor. While it is currently optional it will move to be required in the future.
+
+The breaking part of this change is the modification of the `state` field in the `EntityProcessingRequest` and `EntityProcessingResult` types. This is unlikely to have any impact as the `state` field was previously unused, but could require some minor updates.

.changeset/smart-cooks-drop.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-kubernetes': patch
+---
+
+Added a check for the Kubernetes annotation on the entity

.changeset/spotty-pandas-deny.md

@@ -1,5 +0,0 @@
----
-'@backstage/plugin-scaffolder-backend': patch
----
-
-- Move out the `cookiecutter` templating to its own module that is depended on by the `scaffolder-backend` plugin. No breaking change yet, but we will drop first class support for `cookiecutter` in the future and it will become an opt-in feature.

.changeset/techdocs-fifty-cameras-listen.md

@@ -1,7 +0,0 @@
----
-'@backstage/plugin-techdocs': patch
----
-
-Only update the `path` when the content is updated.
-If content and path are updated independently, the frontend rendering is triggered twice on each navigation: Once for the `path` change (with the old content) and once for the new content.
-This might result in a flickering rendering that is caused by the async frontend preprocessing, and the fact that replacing the shadow dom content is expensive.

.changeset/techdocs-gorgeous-monkeys-remain.md

@@ -0,0 +1,6 @@
+---
+'@backstage/techdocs-common': patch
+---
+
+Add more context to techdocs log lines when files are not found along with
+ensuring that the routers return 404 with a descriptive message.

.changeset/techdocs-proud-apples-wonder.md

@@ -1,5 +0,0 @@
----
-'@backstage/techdocs-common': patch
----
-
-Add link to https://backstage.io/docs/features/techdocs/configuration in the log warning message about updating techdocs.generate key.

.changeset/techdocs-sad-songs-waltzes.md

@@ -0,0 +1,6 @@
+---
+'@backstage/techdocs-common': patch
+---
+
+Locks the version of the default docker image used to generate TechDocs. As of
+this changelog entry, it is v0.3.2!

.changeset/techdocs-young-gorillas-share.md

@@ -1,5 +0,0 @@
----
-'@backstage/plugin-techdocs': patch
----
-
-Handle error responses in `getTechDocsMetadata` and `getEntityMetadata` such that `<TechDocsPageHeader>` doesn't throw errors.

.changeset/thick-rabbits-double.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-auth-backend': patch
+---
+
+Update OAuth refresh handler to pass updated refresh token to ensure cookie is updated with new value.

.changeset/tricky-pens-camp.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog': patch
+---
+
+Update AboutCard to only render refresh button if the entity is managed by an url location.

.changeset/twenty-chairs-argue.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-kubernetes': patch
+---
+
+Add dashboard support for Rancher

.changeset/wicked-emus-deny.md

@@ -1,8 +0,0 @@
----
-'@backstage/create-app': patch
-'@backstage/plugin-scaffolder-backend': patch
----
-
-Moved sample software templates to the [backstage/software-templates](https://github.com/backstage/software-templates) repository. If you previously referenced the sample templates straight from `scaffolder-backend` plugin in the main [backstage/backstage](https://github.com/backstage/backstage) repository in your `app-config.yaml`, these references will need to be updated.
-
-See https://github.com/backstage/software-templates

.changeset/wild-fishes-suffer.md

@@ -1,5 +0,0 @@
----
-'@backstage/dev-utils': patch
----
-
-Allow custom theme for dev app.

.github/CODEOWNERS

@@ -8,17 +8,19 @@
 /docs/features/techdocs                     @backstage/techdocs-core
 /docs/features/search                       @backstage/techdocs-core
 /docs/assets/search                         @backstage/techdocs-core
-/plugins/code-coverage                      @alde @nissayeva
-/plugins/code-coverage-backend              @alde @nissayeva
+/plugins/code-coverage                      @backstage/reviewers @alde @nissayeva
+/plugins/code-coverage-backend              @backstage/reviewers @alde @nissayeva
 /plugins/cost-insights                      @backstage/silver-lining
-/plugins/cloudbuild                         @trivago/ebarrios
+/plugins/cloudbuild                         @backstage/reviewers @trivago/ebarrios
 /plugins/search                             @backstage/techdocs-core
 /plugins/search-*                           @backstage/techdocs-core
 /plugins/techdocs                           @backstage/techdocs-core
 /plugins/techdocs-backend                   @backstage/techdocs-core
-/plugins/ilert                              @yacut
+/plugins/ilert                              @backstage/reviewers @yacut
+/plugins/home                               @backstage/techdocs-core
 /packages/search-common                     @backstage/techdocs-core
 /packages/techdocs-common                   @backstage/techdocs-core
-/.changeset/cost-insights-*                 @backstage/silver-lining
+/.changeset/cost-insights-*                 @backstage/reviewers @backstage/silver-lining
 /.changeset/search-*                        @backstage/techdocs-core
 /.changeset/techdocs-*                      @backstage/techdocs-core
+/cypress/src/integration/plugins/techdocs.spec.ts   @backstage/techdocs-core

.github/ISSUE_TEMPLATE/bug_template.md

@@ -38,6 +38,6 @@ labels: bug
 
 <!--- Include as many relevant details about the environment you experienced the bug in -->
 
-- NodeJS Version (v12):
+- NodeJS Version (v14):
 - Operating System and Version (e.g. Ubuntu 14.04):
 - Browser Information:

.github/styles/vocab.txt

@@ -1,5 +1,6 @@
 abc
 accessors
+Anddddd
 Apdex
 api
 Api
@@ -14,6 +15,7 @@ Avro
 backrub
 Bigtable
 Billett
+Bitbucket
 Bitrise
 Blackbox
 bool
@@ -66,7 +68,6 @@ devs
 discoverability
 Discoverability
 dls
-docgen
 Dockerfile
 dockerfiles
 Dockerize
@@ -74,6 +75,7 @@ dockerode
 Docusaurus
 env
 Env
+elasticsearch
 esbuild
 eslint
 etag
@@ -82,6 +84,8 @@ facto
 failover
 Fargate
 Figma
+firehydrant
+FireHydrant
 Firekube
 Fiverr
 gitbeaker
@@ -93,6 +97,7 @@ GraphQL
 graphviz
 Hackathons
 haproxy
+hardcoded
 Helidon
 Heroku
 hoc
@@ -137,6 +142,7 @@ maintainership
 makefile
 md
 memcache
+memoize
 memoized
 microservice
 microservices
@@ -210,6 +216,7 @@ repo
 Repo
 repos
 rerender
+rerenders
 Reusability
 reusability
 roadmaps
@@ -221,6 +228,7 @@ Routable
 rst
 rsync
 ruleset
+runbook
 sam
 sanitization
 scaffolded

.github/workflows/chromatic-storybook-test.yml

@@ -5,6 +5,7 @@ on:
       - '.github/workflows/chromatic-storybook-test.yml'
       - 'packages/storybook/**'
       - 'packages/core-components/src/**'
+      - '**/*.stories.tsx'
 
 jobs:
   chromatic:
@@ -50,4 +51,5 @@ jobs:
           # projetToken intentionally shared to allow collaborators to run Chromatic on forks
           # https://www.chromatic.com/docs/custom-ci-provider#run-chromatic-on-external-forks-of-open-source-projects
           projectToken: 9tzak77m9nj
-          storybookBuildDir: 'packages/storybook/dist'
+          workingDir: 'packages/storybook'
+          storybookBuildDir: 'dist'

.github/workflows/ci.yml

@@ -10,7 +10,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [12.x, 14.x]
+        node-version: [14.x, 16.x]
 
     services:
       postgres13:
@@ -105,11 +105,8 @@ jobs:
         run: git diff --quiet origin/master HEAD -- yarn.lock
         continue-on-error: true
 
-      - name: verify doc links
-        run: node scripts/verify-links.js
-
       - name: prettier
-        run: yarn prettier:check
+        run: yarn prettier:check '!ADOPTERS.md'
 
       - name: lock
         run: yarn lock:check
@@ -123,8 +120,12 @@ jobs:
       - name: type checking and declarations
         run: yarn tsc:full
 
-      - name: check api reports
-        run: yarn build:api-reports:only --ci
+        # We need to generate the API references as well, so that we can verify the doc links
+      - name: check api reports and generate API reference
+        run: yarn build:api-reports:only --ci --docs
+
+      - name: verify doc links
+        run: node scripts/verify-links.js
 
       - name: build changed packages
         if: ${{ steps.yarn-lock.outcome == 'success' }}

.github/workflows/e2e-win.yml

@@ -17,7 +17,7 @@ jobs:
     strategy:
       matrix:
         os: [windows-latest]
-        node-version: [12.x, 14.x]
+        node-version: [14.x, 16.x]
 
     env:
       CI: true
@@ -25,6 +25,13 @@ jobs:
 
     name: Node ${{ matrix.node-version }} on ${{ matrix.os }}
     steps:
+      # In order to have the create-app template function as if it was downloaded from NPM
+      # we need to make sure we checkout files with LF line endings only
+      - name: Set git to use LF
+        run: |
+          git config --global core.autocrlf false
+          git config --global core.eol lf
+
       - uses: actions/checkout@v2
 
       - name: use node.js ${{ matrix.node-version }}

.github/workflows/e2e.yml

@@ -27,7 +27,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        node-version: [12.x, 14.x]
+        node-version: [14.x, 16.x]
 
     env:
       CI: true

.github/workflows/master-win.yml

@@ -11,7 +11,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [12.x, 14.x]
+        node-version: [14.x, 16.x]
 
     env:
       CI: true

.github/workflows/master.yml

@@ -14,7 +14,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [12.x, 14.x]
+        node-version: [14.x, 16.x]
 
     services:
       postgres13:

.github/workflows/microsite-build-check.yml

@@ -27,9 +27,6 @@ jobs:
         with:
           node-version: ${{ matrix.node-version }}
 
-      - name: verify doc links
-        run: node scripts/verify-links.js
-
         # Skip caching of microsite dependencies, it keeps the global cache size
         # smaller, which make Windows builds a lot faster for the rest of the project.
       - name: yarn install

.github/workflows/microsite-with-storybook-deploy.yml

@@ -4,12 +4,6 @@ on:
   push:
     branches:
       - master
-    paths:
-      - '.github/workflows/microsite-with-storybook-deploy.yml'
-      - 'packages/storybook/**'
-      - 'packages/core-components/src/**'
-      - 'microsite/**'
-      - 'docs/**'
 
 jobs:
   deploy-microsite-and-storybook:
@@ -41,6 +35,9 @@ jobs:
         run: yarn install --frozen-lockfile
         working-directory: microsite
 
+      - name: build API reference
+        run: yarn build:api-docs
+
       - name: build microsite
         run: yarn build
         working-directory: microsite

.github/workflows/prettify.yml

@@ -0,0 +1,54 @@
+name: Prettier
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  autofix-markdown:
+    name: Autofix Markdown files using Prettier
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          # Fetch changes to previous commit - required for 'only_changed' in Prettier action
+          fetch-depth: 0
+
+      # Beginning of yarn setup, keep in sync between all workflows, see ci.yml
+      - name: use node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v1
+        with:
+          node-version: ${{ matrix.node-version }}
+          registry-url: https://registry.npmjs.org/ # Needed for auth
+      - name: cache all node_modules
+        id: cache-modules
+        uses: actions/cache@v2
+        with:
+          path: '**/node_modules'
+          key: ${{ runner.os }}-v${{ matrix.node-version }}-node_modules-${{ hashFiles('yarn.lock', '**/package.json') }}
+      - name: find location of global yarn cache
+        id: yarn-cache
+        if: steps.cache-modules.outputs.cache-hit != 'true'
+        run: echo "::set-output name=dir::$(yarn cache dir)"
+      - name: cache global yarn cache
+        uses: actions/cache@v2
+        if: steps.cache-modules.outputs.cache-hit != 'true'
+        with:
+          path: ${{ steps.yarn-cache.outputs.dir }}
+          key: ${{ runner.os }}-yarn-${{ hashFiles('yarn.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-yarn-
+      - name: yarn install
+        run: yarn install --frozen-lockfile
+      # End of yarn setup
+
+      - name: Run Prettier on ADOPTERS.md
+        uses: creyD/prettier_action@v3.1
+        with:
+          # Modifies commit only if prettier autofixed the ADOPTERS.md
+          prettier_options: --config docs/prettier.config.js --write ADOPTERS.md
+          only_changed: true
+          commit_message: 'Autofix ADOPTERS.md using Prettier'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/snyk-monitor.yml

@@ -0,0 +1,51 @@
+name: Snyk Monitoring
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [master]
+    paths:
+      - '.github/workflows/snyk-monitor.yml'
+      - '**/.snyk'
+      - '**/package.json'
+      - 'yarn.lock'
+
+# This workflow synchronizes the packages in this repo along with policies in
+# each .snyk file with the remote state in our snyk org. It allows us to define
+# ignore policies in the .snyk files and then have them show up in the snyk web
+# UI, and also automatically adds any new packages that are created.
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Monitor and Synchronize Snyk Policies
+        uses: snyk/actions/node@master
+        with:
+          command: monitor
+          args: >
+            --yarn-workspaces
+            --org=backstage-dgh
+            --strict-out-of-sync=false
+            --remote-repo-url=https://github.com/backstage/backstage
+        env:
+          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
+
+      # Above we run the `monitor` command, this runs the `test` command which is
+      # the one that generates the SARIF report that we can upload to GitHub.
+      - name: Create Snyk report
+        uses: snyk/actions/node@master
+        continue-on-error: true # To make sure that SARIF upload gets called
+        with:
+          args: >
+            --yarn-workspaces
+            --org=backstage-dgh
+            --strict-out-of-sync=false
+            --sarif-file-output=snyk.sarif
+        env:
+          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
+      - name: Upload Snyk report
+        uses: github/codeql-action/upload-sarif@v1
+        with:
+          sarif_file: snyk.sarif

.gitignore

@@ -133,3 +133,6 @@ site
 
 # Sensitive credentials
 *-credentials.yaml
+
+# e2e tests
+cypress/cypress/*

.imgbotconfig

@@ -1,5 +1,3 @@
 {
-  "ignoredFiles": [
-    "docs/assets/**/*.svg"
-  ]
+  "ignoredFiles": ["docs/assets/**/*.svg"]
 }

ADOPTERS.md

@@ -1,40 +1,54 @@
-| Organization                                      | Contact                                                                                                                                                                                             | Description of Use                                                                                                                                                                                    |
-| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [Spotify](https://www.spotify.com)                | [@leemills83](https://github.com/leemills83)                                                                                                                                                        | Main interface towards all of Spotify's infrastructure and technical documentation.                                                                                                                   |
-| [bol.com](https://www.bol.com)                    | [@sagacity](https://github.com/sagacity)                                                                                                                                                            | Initial work being done to unify platform tooling.                                                                                                                                                    |
-| [DFDS](https://www.dfds.com)                      | [@carlsendk](https://github.com/carlsendk)                                                                                                                                                          | V2 self-service platform.                                                                                                                                                                             |
-| [Roadie](https://roadie.io)                       | [@dtuite](https://github.com/dtuite)                                                                                                                                                                | Hosted, managed Backstage with easy set-up                                                                                                                                                            |
-| [Roku](https://www.roku.com)                      | [@timurista](https://github.com/timurista)                                                                                                                                                          | Initial work on Cloud engineering service platform.                                                                                                                                                   |
-| [SDA SE](https://sda.se)                          | [@Fox32](https://github.com/Fox32)                                                                                                                                                                  | Central place for developing and sharing services in our insurance ecosystem.                                                                                                                         |
-| [H-E-B](https://www.heb.com)                      | [@german-j-rodriguez](https://github.com/german-j-rodriguez)                                                                                                                                        | Initial work on Engineering Portal service platform.                                                                                                                                                  |
-| [American Airlines](https://www.aa.com)           | [@paulpach](https://github.com/paulpach)                                                                                                                                                            | Central place for developers to develop and maintain applications                                                                                                                                     |
-| [Kiwi.com](https://kiwi.com)                      | [@aexvir](https://github.com/aexvir)                                                                                                                                                                | Replacing the frontend of [The Zoo](https://github.com/kiwicom/the-zoo), their service registry.                                                                                                      |
-| [Voi](https://www.voiscooters.com/)               | [@K-Phoen](https://github.com/K-Phoen)                                                                                                                                                              | Developer portal, main gateway to our infrastructure, documentation and internal tooling.                                                                                                             |
-| [Talkdesk](https://www.talkdesk.com)              | [@jaime-talkdesk](https://github.com/jaime-talkdesk)                                                                                                                                                | Initial work for Engineering Portal and Self Provisioning to R&D                                                                                                                                      |
-| [Wealthsimple](https://www.wealthsimple.com)      | [@andrewthauer](https://github.com/andrewthauer)                                                                                                                                                    | Developer portal, service catalog, documentation and tooling                                                                                                                                          |
-| [Grab](https://www.grab.com)                      | [@althafh](https://github.com/althafh)                                                                                                                                                              | Initial work as a unified interface for all of Grab's internal tooling                                                                                                                                |
-| [Telenor Sweden](https://www.telenor.se)          | [@O5ten](https://github.com/O5ten)                                                                                                                                                                  | Building a developer portal for scaffolding projects towards our unified build environment and microservice stacks                                                                                    |
-| [Fiverr](https://www.fiverr.com)                  | [@nirga](https://github.com/nirga)                                                                                                                                                                  | Unifying separate tools that developers are using today (i.e. monitoring, dead letter queues management, etc.) into a single platform.                                                                |
-| [Zalando SE](https://www.zalando.de)              | [@leviferreira](https://github.com/leviferreira)                                                                                                                                                    | Building V2 of the Internal Development Portal.                                                                                                                                                       |
-| [LegalZoom](https://legalzoom.com)                | [@backjo](https://github.com/backjo)                                                                                                                                                                | Developer portal - hub for all engineering projects and metadata.                                                                                                                                     |
-| [Expedia Group](https://www.expediagroup.com)     | [Mike Turner](mailto:miturner@expediagroup.com), [Sneha Kumar](mailto:snkumar@expediagroup.com), [@guillermomanzo](https://github.com/guillermomanzo), [Erik Lindgren](https://github.com/lindgren) | EG Common Developer Toolkit                                                                                                                                                                           |
-| [Paddle.com](https://paddle.com)                  | [Ioannis Georgoulas](https://github.com/geototti21)                                                                                                                                                 | Developer portal (Tech Docs, Service Catalog, Internal Tooling), we use vanilla Backstage FE and custom BE implementation in Go                                                                       |
-| [Acast.com](https://acast.com)                    | [Olle Lundberg](https://github.com/lndbrg)                                                                                                                                                          | Developer portal with tech docs, service catalog and a bunch of other internal tooling                                                                                                                |
-| [Lunar](https://lunar.app)                        | [Jacob Valdemar](https://github.com/JacobValdemar)                                                                                                                                                  | Internal developer portal for service overview and insights, API documentation, technical guides, onboarding guides and RFC's.                                                                        |
-| [Trendyol](https://trendyol.com)                  | [Erdogan Oksuz](https://github.com/erdoganoksuz)                                                                                                                                                    | The Developer Portal has been called `Pandora`. Provides an overview of Trendyol tech ecosystem. TechDocs, Catalog, Custom Plugins and Theme.                                                         |
-| [Peloton](https://www.onepeloton.com/)            | [Jim Haughwout](https://github.com/JimHaughwout)                                                                                                                                                    | Creating our first developer portal and tech-docs. Exploring Service Catalog, Tech Insights and Cost Insights as well.                                                                                |
-| [TELUS](https://telus.com)                        | [Seb Barre](https://github.com/sbarre)                                                                                                                                                              | The Go-to place to find answers about development and delivery at TELUS.                                                                                                                              |
-| [Brex](https://www.brex.com/)                     | [Vamsi Chitters](https://github.com/vamsikc)                                                                                                                                                        | A centralized UI to understand how a service fits in the whole Brex architecture and manage a team’s engineering dependencies.                                                                        |
-| [Oriflame](https://www.oriflame.com/)             | [Oriflame](https://github.com/oriflame)                                                                                                                                                             | Internal developer portal for services, single page apps and packages overview, API documentation, technical guides, tech-radar and more.                                                             |
-| [Booz Allen Hamilton](https://www.boozallen.com/) | [Jason Miller](https://github.com/JasonMiller-BAH)                                                                                                                                                  | Developer portal for a full-stack software development ecosystem that accelerates consistent and repeatable Modern Software Development practices for internal innovation and investments.            |
-| [Netflix](https://www.netflix.com/)               | [bleathem](https://github.com/bleathem)                                                                                                                                                             | Our Backstage implementation will be the front door to a unified experience connecting our internal platform products across important workflows with integrated knowledge and support.               |
-| [b.well](https://www.icanbwell.com/)              | [Jacob Rosales](https://github.com/jrosales)                                                                                                                                                        | Foundation for our engineering portal and cloud insights.                                                                                                                                             |
-| [PagerDuty](https://www.pagerduty.com/)           | [Mark Shaw](https://github.com/markshawtoronto)                                                                                                                                                     | Developer portal, initially focused on software templates and tech-docs.                                                                                                                              |
-| [MoonShiner](https://moonshiner.at)               | [Fabian Hippmann](https://github.com/FabianHippmann)                                                                                                                                                | Developer portal - helps us keep track of our customer projects, onboard new developers & improve our development process 🌕🚀🧑‍🚀                                                                   |
-| [FundApps](https://www.fundapps.co/)              | [Elliot Greenwood](https://github.com/egnwd)                                                                                                                                                        | Developer Portal - A place for us to keep track of our projects and documentation for all services and processes                                                                                      |
-| [DAZN](https://dazn.com/)                         | [Lou Bichard](https://twitter.com/loujaybee), [Marco Crivellaro](https://github.com/crivetechie), [Alex Hollerith](mailto:alex.hollerith@dazn.com)                                                  | Ingesting all of DAZN's repos for the catalog, migrating our internal platform apps (pull request boards, release information, inner source marketplace etc) to Backstage plugins (where applicable). |
-| [HelloFresh](https://www.hellofresh.de/)          | [@iammuho](https://github.com/iammuho), [@ElenaForester](https://github.com/ElenaForester), [@diegomarangoni](https://github.com/diegomarangoni)                                                    | Our developer portal at HelloFresh - Spread across an organisation of 500+ engineers globally.                                                                                                        |
-| [FactSet](https://www.factset.com/)               | [@kuangp](https://github.com/kuangp)                                                                                                                                                                | Developer portal to provide discoverability to all internal components, APIs, documentation, and scaffold templates with integrations to our internal infrastructure tools.                           |
-| [Workrise](https://www.workrise.com/)             | [Michael Rode](https://github.com/michaelrode)                                                                                                                                                      | Developer portal, main gateway to our infrastructure, documentation and internal tooling.                                                                                                             |
-| [RedVentures](https://www.redventures.com/)       | [Chris Diaz](https://github.com/codingdiaz)                                                                                                                                                         | Developer portal that brings everything an engineer needs to provide value into a single pane of glass.                                                                                               |
-| [MavTek](https://www.mavtek.com/)                 | [@fgascon](https://github.com/fgascon)                                                                                                                                                              | Developer portal focused on standardizing practices, centralizing documentation and streamlining developer practices.                                                                                 |
+| Organization                                                             | Contact                                                                                                                                                                                             | Description of Use                                                                                                                                                                                    |
+| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Spotify](https://www.spotify.com)                                       | [@leemills83](https://github.com/leemills83)                                                                                                                                                        | Main interface towards all of Spotify's infrastructure and technical documentation.                                                                                                                   |
+| [bol.com](https://www.bol.com)                                           | [@sagacity](https://github.com/sagacity)                                                                                                                                                            | Initial work being done to unify platform tooling.                                                                                                                                                    |
+| [DFDS](https://www.dfds.com)                                             | [@carlsendk](https://github.com/carlsendk)                                                                                                                                                          | V2 self-service platform.                                                                                                                                                                             |
+| [Roadie](https://roadie.io)                                              | [@dtuite](https://github.com/dtuite)                                                                                                                                                                | Hosted, managed Backstage with easy set-up                                                                                                                                                            |
+| [Roku](https://www.roku.com)                                             | [@timurista](https://github.com/timurista)                                                                                                                                                          | Initial work on Cloud engineering service platform.                                                                                                                                                   |
+| [SDA SE](https://sda.se)                                                 | [@Fox32](https://github.com/Fox32)                                                                                                                                                                  | Central place for developing and sharing services in our insurance ecosystem.                                                                                                                         |
+| [H-E-B](https://www.heb.com)                                             | [@german-j-rodriguez](https://github.com/german-j-rodriguez)                                                                                                                                        | Initial work on Engineering Portal service platform.                                                                                                                                                  |
+| [American Airlines](https://www.aa.com)                                  | [@paulpach](https://github.com/paulpach)                                                                                                                                                            | Central place for developers to develop and maintain applications                                                                                                                                     |
+| [Kiwi.com](https://kiwi.com)                                             | [@aexvir](https://github.com/aexvir)                                                                                                                                                                | Replacing the frontend of [The Zoo](https://github.com/kiwicom/the-zoo), their service registry.                                                                                                      |
+| [Voi](https://www.voiscooters.com/)                                      | [@K-Phoen](https://github.com/K-Phoen)                                                                                                                                                              | Developer portal, main gateway to our infrastructure, documentation and internal tooling.                                                                                                             |
+| [Talkdesk](https://www.talkdesk.com)                                     | [@jaime-talkdesk](https://github.com/jaime-talkdesk)                                                                                                                                                | Initial work for Engineering Portal and Self Provisioning to R&D                                                                                                                                      |
+| [Wealthsimple](https://www.wealthsimple.com)                             | [@andrewthauer](https://github.com/andrewthauer)                                                                                                                                                    | Developer portal, service catalog, documentation and tooling                                                                                                                                          |
+| [Grab](https://www.grab.com)                                             | [@althafh](https://github.com/althafh)                                                                                                                                                              | Initial work as a unified interface for all of Grab's internal tooling                                                                                                                                |
+| [Telenor Sweden](https://www.telenor.se)                                 | [@O5ten](https://github.com/O5ten)                                                                                                                                                                  | Building a developer portal for scaffolding projects towards our unified build environment and microservice stacks                                                                                    |
+| [Fiverr](https://www.fiverr.com)                                         | [@nirga](https://github.com/nirga)                                                                                                                                                                  | Unifying separate tools that developers are using today (i.e. monitoring, dead letter queues management, etc.) into a single platform.                                                                |
+| [Zalando SE](https://www.zalando.de)                                     | [@leviferreira](https://github.com/leviferreira)                                                                                                                                                    | Building V2 of the Internal Development Portal.                                                                                                                                                       |
+| [LegalZoom](https://legalzoom.com)                                       | [@backjo](https://github.com/backjo)                                                                                                                                                                | Developer portal - hub for all engineering projects and metadata.                                                                                                                                     |
+| [Expedia Group](https://www.expediagroup.com)                            | [Mike Turner](mailto:miturner@expediagroup.com), [Sneha Kumar](mailto:snkumar@expediagroup.com), [@guillermomanzo](https://github.com/guillermomanzo), [Erik Lindgren](https://github.com/lindgren) | EG Common Developer Toolkit                                                                                                                                                                           |
+| [Paddle.com](https://paddle.com)                                         | [Ioannis Georgoulas](https://github.com/geototti21)                                                                                                                                                 | Developer portal (Tech Docs, Service Catalog, Internal Tooling), we use vanilla Backstage FE and custom BE implementation in Go                                                                       |
+| [Acast.com](https://acast.com)                                           | [Olle Lundberg](https://github.com/lndbrg)                                                                                                                                                          | Developer portal with tech docs, service catalog and a bunch of other internal tooling                                                                                                                |
+| [Lunar](https://lunar.app)                                               | [Jacob Valdemar](https://github.com/JacobValdemar)                                                                                                                                                  | Internal developer portal for service overview and insights, API documentation, technical guides, onboarding guides and RFC's.                                                                        |
+| [Trendyol](https://trendyol.com)                                         | [Gamze Senturk](https://github.com/gmzsenturk), [Mert Can Bilgic](https://github.com/mertcb)                                                                                                        | The Developer Portal has been called `Pandora`. Provides an overview of Trendyol tech ecosystem. TechDocs, Catalog, Custom Plugins and Theme.                                                         |
+| [Peloton](https://www.onepeloton.com/)                                   | [Jim Haughwout](https://github.com/JimHaughwout)                                                                                                                                                    | Creating our first developer portal and tech-docs. Exploring Service Catalog, Tech Insights and Cost Insights as well.                                                                                |
+| [TELUS](https://telus.com)                                               | [Seb Barre](https://github.com/sbarre)                                                                                                                                                              | The Go-to place to find answers about development and delivery at TELUS.                                                                                                                              |
+| [Brex](https://www.brex.com/)                                            | [Vamsi Chitters](https://github.com/vamsikc)                                                                                                                                                        | A centralized UI to understand how a service fits in the whole Brex architecture and manage a team’s engineering dependencies.                                                                        |
+| [Oriflame](https://www.oriflame.com/)                                    | [Oriflame](https://github.com/oriflame)                                                                                                                                                             | Internal developer portal for services, single page apps and packages overview, API documentation, technical guides, tech-radar and more.                                                             |
+| [Booz Allen Hamilton](https://www.boozallen.com/)                        | [Jason Miller](https://github.com/JasonMiller-BAH)                                                                                                                                                  | Developer portal for a full-stack software development ecosystem that accelerates consistent and repeatable Modern Software Development practices for internal innovation and investments.            |
+| [Netflix](https://www.netflix.com/)                                      | [bleathem](https://github.com/bleathem)                                                                                                                                                             | Our Backstage implementation will be the front door to a unified experience connecting our internal platform products across important workflows with integrated knowledge and support.               |
+| [b.well](https://www.icanbwell.com/)                                     | [Jacob Rosales](https://github.com/jrosales)                                                                                                                                                        | Foundation for our engineering portal and cloud insights.                                                                                                                                             |
+| [PagerDuty](https://www.pagerduty.com/)                                  | [Mark Shaw](https://github.com/markshawtoronto)                                                                                                                                                     | Developer portal, initially focused on software templates and tech-docs.                                                                                                                              |
+| [MoonShiner](https://moonshiner.at)                                      | [Fabian Hippmann](https://github.com/FabianHippmann)                                                                                                                                                | Developer portal - helps us keep track of our customer projects, onboard new developers & improve our development process 🌕🚀🧑‍🚀                                                                   |
+| [FundApps](https://www.fundapps.co/)                                     | [Elliot Greenwood](https://github.com/egnwd)                                                                                                                                                        | Developer Portal - A place for us to keep track of our projects and documentation for all services and processes                                                                                      |
+| [DAZN](https://dazn.com/)                                                | [Lou Bichard](https://twitter.com/loujaybee), [Marco Crivellaro](https://github.com/crivetechie), [Alex Hollerith](mailto:alex.hollerith@dazn.com)                                                  | Ingesting all of DAZN's repos for the catalog, migrating our internal platform apps (pull request boards, release information, inner source marketplace etc) to Backstage plugins (where applicable). |
+| [HelloFresh](https://www.hellofresh.de/)                                 | [@iammuho](https://github.com/iammuho), [@ElenaForester](https://github.com/ElenaForester), [@diegomarangoni](https://github.com/diegomarangoni)                                                    | Our developer portal at HelloFresh - Spread across an organisation of 500+ engineers globally.                                                                                                        |
+| [FactSet](https://www.factset.com/)                                      | [@kuangp](https://github.com/kuangp)                                                                                                                                                                | Developer portal to provide discoverability to all internal components, APIs, documentation, and scaffold templates with integrations to our internal infrastructure tools.                           |
+| [Workrise](https://www.workrise.com/)                                    | [Michael Rode](https://github.com/michaelrode)                                                                                                                                                      | Developer portal, main gateway to our infrastructure, documentation and internal tooling.                                                                                                             |
+| [RedVentures](https://www.redventures.com/)                              | [Chris Diaz](https://github.com/codingdiaz)                                                                                                                                                         | Developer portal that brings everything an engineer needs to provide value into a single pane of glass.                                                                                               |
+| [MavTek](https://www.mavtek.com/)                                        | [@fgascon](https://github.com/fgascon)                                                                                                                                                              | Developer portal focused on standardizing practices, centralizing documentation and streamlining developer practices.                                                                                 |
+| [QuintoAndar](https://www.quintoandar.com.br/)                           | [@quintoandar](https://github.com/quintoandar)                                                                                                                                                      | Developer portal, services catalog and centralization of service metrics.                                                                                                                             |
+| [empathy.co](https://empathy.co/)                                        | [@guillermotti](https://github.com/guillermotti)                                                                                                                                                    | Developer portal for tech docs, service catalog, plugin discovery and much more.                                                                                                                      |
+| [creditas.com](https://creditas.com/)                                    | [@aureliosaraiva](https://github.com/aureliosaraiva) [@Creditas](https://github.com/creditas)                                                                                                       | Centralization of all services, standards, documentation, etc. We started the deployment process.                                                                                                     |
+| [Prisjakt](https://www.prisjakt.nu) / [PriceSpy](https://pricespy.co.uk) | [@kennylindahl](https://github.com/kennylindahl)                                                                                                                                                    | Internal developer portal - Documentation, scaffolding, software catalog, TechRadar, Gitlab org data integration                                                                                      |
+| [Powerspike](https://powerspike.tv/)                                     | [@trelore](https://github.com/trelore)                                                                                                                                                              | Developer portal for documentation of core libraries and repositories.                                                                                                                                |
+| [2U](https://2u.com)                                                     | [Andrew Thal](https://github.com/athal7)      | Development team home-base, promoting service discoverability, resource dependencies, and tech radar |
+| [Taxfix](https://taxfix.de/)                                                     | [Sami Ur Rehman](https://github.com/samiurrehman92)      | Developer's portal with software catalog at it's core. Hosts API Specs, Tech Docs, Tech Radar and some custom plugins.  |
+| [Busuu](https://busuu.com/)                                                     | [Adam Tester](https://github.com/adamtester)      | Developer portal with service catalog, API docs, Event docs, service templating, and cost insights.  |
+| [Loadsmart](https://loadsmart.com/)                                                     | [Loadsmart](https://github.com/loadsmart)      | Improve services visibility and operations for service owners and developers.  |
+| [Monzo](https://monzo.com/)                                              | [@WillSewell](https://github.com/WillSewell), [@joechrisellis](https://github.com/joechrisellis)                                                                                                    | Developer portal showing metadata and docs for over 2000 microservices. We have built a number of plugins such as a UI for our system to measure [software excellence](https://monzo.com/blog/2021/09/15/how-we-measure-software-excellence), and a UI to show deployment and config change events. |
+| [Vaimo](https://www.vaimo.com)                                       | [@vaimo-magnus](https://github.com/vaimo-magnus)                                                                                                                                                        | Developer Portal for our developers at Vaimo, currently docs and self-service towards our internal PaaS based on k8s. Plans to extend the catalog into Projects, Environments etc |
+| [Wayfair](https://www.wayfair.com)                                       | [@fransan](https://github.com/fransan), [@errskipower](https://github.com/errskipower), [@hrrs](https://github.com/hrrs)                                                                            | Developer portal for service catalog, technical documentation, and APIs.                                                                                                                   |
+| [CircleHD](https://www.circlehd.com)                                       | [@circlehddev](https://github.com/circlehddev)                                                                                                                                                    | Developer Portal for internal dev team across the globe |
+| [CastDesk](https://castdesk.com)                                       | [@circlehddev](https://github.com/circlehddev)                                                                                                                                                    	 | Developer Portal for internal dev team across the globe |

CONTRIBUTING.md

@@ -102,6 +102,18 @@ Signed-off-by: Jane Smith <jane.smith@example.com>
 
 Note: If you have already pushed you branch to a remote, you might have to force push: `git push -f` after the rebase.
 
+### Using GitHub Desktop?
+
+If you are using the GitHub Desktop client, you need to manually add the `Signed-off-by` line to the Description field on the Changes tab before committing:
+
+```
+Awesome description (commit message)
+
+Signed-off-by: Jane Smith <jane.smith@example.com>
+```
+
+In case you forgot to add the line to your most recent commit, you can amend the commit message from the History tab before pushing your branch (GitHub Desktop 2.9 or later).
+
 ## Creating Changesets
 
 We use [changesets](https://github.com/atlassian/changesets) to help us prepare releases. They help us make sure that every package affected by a change gets a proper version number and an entry in its `CHANGELOG.md`. To make the process of generating releases easy, it helps when contributors include changesets with their pull requests.
@@ -116,7 +128,7 @@ In general, changesets are not needed for the documentation, build utilities, co
 
 1. Run `yarn changeset`
 2. Select which packages you want to include a changeset for
-3. Select impact of change that you're introducing (patch, minor, or major)
+3. Select impact of change that you're introducing, using `minor` for breaking changes and `patch` otherwise. We do not use `major` changes while packages are at version `0.x`.
 4. Add generated changeset to Git
 5. Push the commit with your changeset to the branch associated with your PR
 6. Accept our gratitude for making the release process easier on the maintainers

README.md

@@ -2,8 +2,6 @@
 
 # [Backstage](https://backstage.io)
 
-_During the month of July the majority of the maintainers will be on summer vacation 🏖️ Development will continue as usual, but expect a slower pace for discussions and PR reviews. Why not take this opportunity to [build a plugin](https://backstage.io/docs/plugins/)?_
-
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![CNCF Status](https://img.shields.io/badge/cncf%20status-sandbox-blue.svg)](https://www.cncf.io/projects)
 [![Main CI Build](https://github.com/backstage/backstage/workflows/Main%20Master%20Build/badge.svg)](https://github.com/backstage/backstage/actions?query=workflow%3A%22Main+Master+Build%22)
@@ -63,3 +61,9 @@ Check out [the documentation](https://backstage.io/docs/getting-started) on how
 Copyright 2020-2021 © The Backstage Authors. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Usage page: https://www.linuxfoundation.org/trademark-usage
 
 Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0
+
+## Security
+
+Please report sensitive security issues via Spotify's [bug-bounty program](https://hackerone.com/spotify) rather than GitHub.
+
+For further details please see our complete [security release process](SECURITY.md).

SECURITY.md

@@ -9,3 +9,30 @@
 ## Reporting a Vulnerability
 
 Please report sensitive security issues via Spotify's [bug-bounty program](https://hackerone.com/spotify) rather than GitHub.
+
+If you have questions about a potential vulnerability, please reach out on Discord by asking for a maintainer in the `#support` channel, or via direct message to a maintainer.
+
+## Remediation and Notification Process
+
+Vulnerabilities are handled and published through [GitHub Security Advisories](https://docs.github.com/en/code-security/security-advisories/about-github-security-advisories).
+
+In the event of a vulnerability the runbook for the maintainers is as follows:
+
+1. Create a [new draft security advisory](https://github.com/backstage/backstage/security/advisories/new). The values and descriptions don't need to be perfect to begin with as they can be edited later. For severity, use the "Assess severity using CVSS" and refer to [the guide](https://www.first.org/cvss/v3.1/user-guide) for help.
+2. Request a CVE identification number. It can take up to 72h for one to be assigned so be sure to do this early on.
+3. If there is not already a patch for the vulnerability, collaborate on one in a private fork:
+   1. Head to the security advisory on GitHub and [create a private fork](https://docs.github.com/en/code-security/security-advisories/collaborating-in-a-temporary-private-fork-to-resolve-a-security-vulnerability)
+   1. [Invite any collaborators](https://docs.github.com/en/code-security/security-advisories/adding-a-collaborator-to-a-security-advisory) from outside the maintainer team that should be part of creating a fix.
+   1. Create one or multiple Pull Requests with fixes towards the fork. Note that these PRs will not have CI checks run on them, so more care should be taken to run local validation. The PRs are also not merged like normal PRs, but are instead merged straight into the main repo all at once when the merge button is hit on the security advisory.
+4. Once the fix is ready in a PR or private fork and it is time to release it, there are a couple of options. Either merge into the main branch with a changeset and wait for a regular release, or do a quick release by manually bumping the version in `package.json` of the affected package, along with a manual `CHANGELOG.md` entry. Note that a quick release will only work if the package does not have any other pending changes that depend on pending changes in other packages, so be sure to manually check that first, and fall back to an early regular release if needed. In general it's best to stick with the regular release flow, with the quick release being used only for time sensitive fixes.
+5. Finalize and publish the security advisory. Note that once you hit the publish button it's no longer possible to edit the advisory. Just like the CVE number this can take up to 72h, and expect it to be slower than the CVE number request.
+
+## Vulnerability Policies
+
+Backstage uses Snyk vulnerability scans in order to make sure we minimize vulnerabilities in our dependencies and get notified of new vulnerabilities.
+
+There are many situations where a vulnerability does not affect a particular dependency because of how the vulnerable package is used. In that situation the package authors may choose to stay at the current version rather than bumping the dependency, leading to a warning in the vulnerability scans but no actual vulnerability.
+
+To work around this and other similar issues, Snyk provides a method to ignore vulnerabilities. In order to provide the best visibility and most utility to adopters of Backstage, we store these ignore rules in `.snyk` policy files. This allows adopters to rely on our ignore policies if they wish to do so.
+
+Adding a new ignore policy is done by creating or modifying an existing `.snyk` file within a package root. See the [Snyk Documentation](https://support.snyk.io/hc/en-us/articles/360007487097-The-snyk-file) for details on the syntax. Always include a description, full path, and time limit of the ignore policy.

app-config.yaml

@@ -133,6 +133,9 @@ kafka:
       brokers:
         - localhost:9092
 
+allure:
+  baseUrl: http://localhost:5050/allure-docker-service
+
 integrations:
   github:
     - host: github.com
@@ -152,12 +155,21 @@ integrations:
     - host: bitbucket.org
       username: ${BITBUCKET_USERNAME}
       appPassword: ${BITBUCKET_APP_PASSWORD}
+    ### Example for how to add your bitbucket server instance using the API:
+    # - host: server.bitbucket.com
+    #   apiBaseUrl: server.bitbucket.com
+    #   username: ${BITBUCKET_SERVER_USERNAME}
+    #   appPassword: ${BITBUCKET_SERVER_APP_PASSWORD}
   azure:
     - host: dev.azure.com
       token: ${AZURE_TOKEN}
-#  googleGcs:
-#    clientEmail: 'example@example.com'
-#    privateKey: ${GCS_PRIVATE_KEY}
+  #  googleGcs:
+  #    clientEmail: 'example@example.com'
+  #    privateKey: ${GCS_PRIVATE_KEY}
+  awsS3:
+    - host: amazonaws.com
+      accessKeyId: ${AWS_ACCESS_KEY_ID}
+      secretAccessKey: ${AWS_SECRET_ACCESS_KEY}
 
 catalog:
   rules:
@@ -250,12 +262,16 @@ catalog:
     # Backstage example groups and users
     - type: file
       target: ../catalog-model/examples/acme-corp.yaml
-
+    # Backstage end-to-end tests of TechDocs
+    - type: file
+      target: ../../cypress/e2e-fixture.catalog.info.yaml
 scaffolder:
   # Use to customize default commit author info used when new components are created
   # defaultAuthor:
   #   name: Scaffolder
   #   email: scaffolder@backstage.io
+  # Use to customize the default commit message when new components are created
+  # defaultCommitMessage: 'Initial commit'
   github:
     token: ${GITHUB_TOKEN}
     visibility: public # or 'internal' or 'private'
@@ -298,6 +314,7 @@ auth:
     saml:
       entryPoint: 'http://localhost:7001/'
       issuer: 'passport-saml'
+      cert: 'fake-cert-base64'
     okta:
       development:
         clientId: ${AUTH_OKTA_CLIENT_ID}
@@ -367,6 +384,31 @@ costInsights:
       default: true
     MSC:
       name: Monthly Subscribers
+  currencies:
+    engineers:
+      label: 'Engineers 🛠'
+      unit: 'engineer'
+    usd:
+      label: 'US Dollars 💵'
+      kind: 'USD'
+      unit: 'dollar'
+      prefix: '$'
+      rate: 1
+    carbonOffsetTons:
+      label: 'Carbon Offset Tons ♻️⚖️s'
+      kind: 'CARBON_OFFSET_TONS'
+      unit: 'carbon offset ton'
+      rate: 3.5
+    beers:
+      label: 'Beers 🍺'
+      kind: 'BEERS'
+      unit: 'beer'
+      rate: 4.5
+    pintsIceCream:
+      label: 'Pints of Ice Cream 🍦'
+      kind: 'PINTS_OF_ICE_CREAM'
+      unit: 'ice cream pint'
+      rate: 5.5
 homepage:
   clocks:
     - label: UTC
@@ -385,3 +427,8 @@ jenkins:
       baseUrl: https://jenkins.example.com
       username: backstage-bot
       apiKey: 123456789abcdef0123456789abcedf012
+
+azureDevOps:
+  host: dev.azure.com
+  token: my-token
+  organization: my-company

catalog-info.yaml

@@ -15,7 +15,7 @@ metadata:
       url: https://discord.com/invite/EBHEGzX
   annotations:
     github.com/project-slug: backstage/backstage
-    backstage.io/techdocs-ref: url:https://github.com/backstage/backstage
+    backstage.io/techdocs-ref: dir:.
     lighthouse.com/website-url: https://backstage.io
 spec:
   type: library

contrib/docker/frontend-with-nginx/Dockerfile.hostbuild

@@ -8,7 +8,6 @@
 # simply copies in the build output into the image. If you want to also perform
 # the build itself inside docker, use Dockerfile.build in this folder instead.
 
-
 # USAGE:
 #
 # - Copy this file and the "docker" folder from this directory to your project
@@ -23,7 +22,7 @@
 #
 #       yarn install
 #       yarn tsc
-#       yarn build --config <config1> --config <config2> ...
+#       yarn workspace app build --config <config1> --config <config2> ...
 #       docker build -t backstage-frontend -f Dockerfile.hostbuild .
 
 
@@ -38,4 +37,3 @@ COPY docker/default.conf.template /etc/nginx/templates/default.conf.template
 COPY docker/inject-config.sh /docker-entrypoint.d/40-inject-config.sh
 
 ENV PORT 80
-

contrib/docker/frontend-with-nginx/docker/inject-config.sh

@@ -23,7 +23,7 @@ function inject_config() {
 
   # escape ' and " twice, for both sed and json
   local config_escaped_1
-  config_escaped_1="$(echo "$config" | jq -cM . | sed -e 's/[\\"\x27]/\\&/g')" # \x27 = '
+  config_escaped_1="$(echo "$config" | jq -cM . | sed -e 's/[\\"'\'']/\\&/g')"
   # escape / and & for sed
   local config_escaped_2
   config_escaped_2="$(echo "$config_escaped_1" | sed -e 's/[\/&]/\\&/g')"

contrib/docker/kubernetes-example-backend/Dockerfile

@@ -1,4 +1,4 @@
-FROM node:12-buster
+FROM node:14-buster
 
 WORKDIR /usr/src/app
 

contrib/docs/tutorials/authenticate-api-requests.md

@@ -188,9 +188,9 @@ Assuming you follow the common plugin structure, the changes to your front-end m
 
 ```diff
 // plugins/internal-plugin/src/api.ts
--  import {createApiRef} from '@backstage/core';
-+  import {createApiRef, IdentityApi} from '@backstage/core';
-import {Config} from '@backstage/config';
+-  import { createApiRef } from '@backstage/core-plugin-api';
++  import { createApiRef, IdentityApi } from '@backstage/core-plugin-api';
+import { Config } from '@backstage/config';
 // ...
 
 type MyApiOptions = {
@@ -237,14 +237,14 @@ import {
     createApiFactory,
     createPlugin,
 +   identityApiRef,
-} from '@backstage/core';
-import {mypluginPageRouteRef} from './routeRefs';
-import {MyApi, myApiRef} from './api';
+} from '@backstage/core-plugin-api';
+import { myPluginPageRouteRef } from './routeRefs';
+import { MyApi, myApiRef } from './api';
 
 export const plugin = createPlugin({
     id: 'my-plugin',
     routes: {
-        mainPage: mypluginPageRouteRef,
+        mainPage: myPluginPageRouteRef,
     },
     apis: [
         createApiFactory({
@@ -253,9 +253,9 @@ export const plugin = createPlugin({
                 configApi: configApiRef,
 +               identityApi: identityApiRef,
             },
--           factory: ({configApi}) =>
+-           factory: ({ configApi }) =>
 -               new MyApi({ configApi }),
-+           factory: ({configApi, identityApi}) =>
++           factory: ({ configApi, identityApi }) =>
 +               new MyApi({ configApi, identityApi }),
         }),
     ],

contrib/docs/tutorials/aws-deployment.md

@@ -5,7 +5,7 @@ image](https://backstage.io/docs/getting-started/deployment-docker); this
 tutorial shows how to deploy that Docker image to AWS using Elastic Container
 Registry (ECR) and Elastic Kubernetes Service (EKS). Amazon also supports
 deployments with Helm, covered in the [Helm
-Kubernetes](../kubernetes/basic_kubernetes_example_with_helm) example.
+Kubernetes](../../kubernetes/basic_kubernetes_example_with_helm) example.
 
 The basic workflow for this method is to build a Backstage Docker image, upload
 the new version to a container registry, and update a Kubernetes deployment with

cypress/.eslintrc.js

@@ -11,6 +11,7 @@ module.exports = {
         bundledDependencies: false,
       },
     ],
+    'jest/valid-expect': 'off',
     'jest/expect-expect': 'off',
     'no-restricted-syntax': 'off',
   },

cypress/cypress.json

@@ -2,7 +2,9 @@
   "baseUrl": "http://localhost:7000",
   "integrationFolder": "./src/integration",
   "supportFile": "./src/support",
-  "fixturesFolder": "./src/fixures",
+  "fixturesFolder": "./src/fixtures",
   "pluginsFile": "./src/plugins",
-  "defaultCommandTimeout": 10000
+  "defaultCommandTimeout": 10000,
+  "viewportHeight": 900,
+  "viewportWidth": 1440
 }

cypress/e2e-fixture.catalog.info.yaml

@@ -0,0 +1,11 @@
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: techdocs-e2e-fixture
+  description: Used for end-to-end tests of TechDocs in Backstage.
+  annotations:
+    backstage.io/techdocs-ref: dir:./fixtures
+spec:
+  type: service
+  lifecycle: experimental
+  owner: user:guest

cypress/fixtures/docs/index.md

@@ -0,0 +1,3 @@
+# Home page
+
+This is a basic documentation used for end-to-end tests.

cypress/fixtures/docs/sub-page-one.md

@@ -0,0 +1,109 @@
+# Sub-page 1
+
+## Section 1.1
+
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+
+## Section 1.2
+
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+
+## Section 1.3
+
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!

cypress/fixtures/docs/sub-page-three.md

@@ -0,0 +1,121 @@
+# Sub-page 3
+
+## Section 3.1
+
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+
+## Section 3.2
+
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+
+### Sub-Section 3.2.1
+
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+
+### Sub-Section 3.2.2
+
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+
+## Section 3.3
+
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!

cypress/fixtures/docs/sub-page-two.md

@@ -0,0 +1,146 @@
+# Sub-page 2
+
+## Section 2.1
+
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+
+## Section 2.2
+
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+
+### Sub-Section 2.2.1
+
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+
+### Sub-Section 2.2.2
+
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+
+## Section 2.3
+
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+To next page!
+
+[Link to Section 1.1](sub-page-one.md#section-11)

cypress/fixtures/mkdocs.yml

@@ -0,0 +1,10 @@
+site_name: e2e Fixture Documentation
+site_description: Documentation used for end-to-end tests of TechDocs in Backstage.
+nav:
+  - Home: index.md
+  - Sub-page 1: sub-page-one.md
+  - Sub-page 2: sub-page-two.md
+  - Nested Sub-pages:
+      - Sub-page 3: sub-page-three.md
+plugins:
+  - techdocs-core

cypress/src/integration/plugins/techdocs.spec.ts

@@ -0,0 +1,188 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/// <reference types="cypress" />
+import 'os';
+
+describe('TechDocs', () => {
+  beforeEach(() => {
+    cy.loginAsGuest();
+    cy.mockSockJSNode();
+    cy.interceptTechDocsAPICalls();
+  });
+
+  describe('Navigating to TechDocs', () => {
+    it('should navigate to the TechDocs home page via the primary navigation bar', () => {
+      cy.visit('/');
+      cy.wait(500);
+
+      cy.get('[data-testid="sidebar-root"]')
+        .get('div')
+        .get('a[href="/docs"]')
+        .click();
+
+      cy.contains('Documentation');
+    });
+
+    it('should navigate to the TechDocs home page from the URL', () => {
+      cy.visit('/docs');
+      cy.wait(500);
+
+      cy.contains('Documentation');
+    });
+
+    it('should navigate to a specific TechDocs entity from the "Overview" tab', () => {
+      cy.visit('/docs');
+      cy.contains('techdocs-e2e-fixture')
+        .parents()
+        .eq(2)
+        .contains('Read Docs')
+        .click();
+
+      cy.location().should(loc => {
+        expect(loc.pathname).to.eq(
+          '/docs/default/Component/techdocs-e2e-fixture',
+        );
+      });
+    });
+
+    it('should navigate to a specific TechDocs entity page from a URL', () => {
+      cy.visit('/docs/default/Component/techdocs-e2e-fixture');
+      cy.waitHomePage();
+
+      cy.contains('e2e Fixture Documentation');
+      cy.contains(
+        'Documentation used for end-to-end tests of TechDocs in Backstage.',
+      );
+      cy.getTechDocsShadowRoot().contains('Home page');
+    });
+
+    it('should navigate to a specific TechDocs section from a URL', () => {
+      cy.visit('/docs/default/Component/techdocs-e2e-fixture/sub-page-two');
+      cy.waitSectionTwoPage();
+
+      cy.window().its('scrollY').should('equal', 0);
+
+      cy.getTechDocsShadowRoot().within(() => {
+        cy.contains('Sub-page 2');
+      });
+    });
+
+    it('should navigate to a specific TechDocs fragment from a URL', () => {
+      cy.visit(
+        '/docs/default/Component/techdocs-e2e-fixture/sub-page-two#section-23',
+      );
+      cy.waitSectionTwoPage();
+
+      // This is used to test the post-render behavior of the techdocs Reader
+      cy.wait(500);
+
+      cy.getTechDocsShadowRoot().within(() => {
+        cy.isInViewport('#section-23');
+      });
+    });
+
+    it('should navigate to a wrong TechDocs entity page from a URL', () => {
+      cy.visit('/docs/default/Component/wrong-component');
+
+      cy.get('[data-testid=error]').should('be.visible');
+    });
+  });
+
+  describe('Navigating within TechDocs', () => {
+    it('should navigate to a specific TechDocs page via the navigation bar', () => {
+      cy.visit('/docs/default/Component/techdocs-e2e-fixture');
+      cy.waitHomePage();
+
+      cy.getTechDocsShadowRoot().within(() => {
+        cy.getTechDocsNavigation()
+          .find('> div > div > [data-md-level="0"] > ul > li:nth-child(2) > a')
+          .click();
+        cy.contains('Sub-page 1');
+        cy.window().its('scrollY').should('eq', 0);
+      });
+    });
+
+    describe('Navigating within a TechDocs page', () => {
+      beforeEach(() => {
+        cy.visit('/docs/default/Component/techdocs-e2e-fixture/sub-page-two');
+        cy.waitSectionTwoPage();
+      });
+      it('should navigate to a specific fragment within the page via the table of contents - Level 1', () => {
+        return cy.getTechDocsShadowRoot().within(() => {
+          // Section 3
+          cy.getTechDocsTableOfContents().within(() => {
+            cy.get('> div > div > nav > ul > li:nth-child(3) > a').click();
+          });
+
+          cy.isInViewport('#section-23');
+        });
+      });
+
+      it('should navigate to a specific fragment within the page via the table of contents - Level 2', () => {
+        return cy.getTechDocsShadowRoot().within(() => {
+          cy.isNotInViewport('#sub-section-222');
+          // Section 2.2
+          cy.getTechDocsTableOfContents()
+            .find(
+              '> div > div > nav > ul > li:nth-child(2) > nav > ul > li:nth-child(2) > a',
+            )
+            .click();
+
+          cy.isInViewport('#sub-section-222');
+        });
+      });
+
+      it('should navigate to a specific TechDocs page fragment from a link', () => {
+        return cy.getTechDocsShadowRoot().within(() => {
+          cy.get('.md-content > article')
+            .contains('Link to Section 1.1')
+            .click();
+
+          cy.location().should(loc => {
+            expect(loc.pathname).to.eq(
+              '/docs/default/Component/techdocs-e2e-fixture/sub-page-one/',
+            );
+            expect(loc.hash).to.eq('#section-11');
+          });
+        });
+      });
+
+      it('should navigate to the next page within a TechDocs entity', () => {
+        return cy.getTechDocsShadowRoot().within(() => {
+          cy.get('.md-footer-nav__link--next').click();
+
+          cy.location().should(loc => {
+            expect(loc.pathname).to.eq(
+              '/docs/default/Component/techdocs-e2e-fixture/sub-page-three/',
+            );
+          });
+        });
+      });
+
+      it('should navigate to the previous page within a TechDocs entity', () => {
+        return cy.getTechDocsShadowRoot().within(() => {
+          cy.get('.md-footer-nav__link--prev').click();
+
+          cy.location().should(loc => {
+            expect(loc.pathname).to.eq(
+              '/docs/default/Component/techdocs-e2e-fixture/sub-page-one/',
+            );
+          });
+        });
+      });
+    });
+  });
+});

cypress/src/integration/user/login.spec.ts

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/// <reference types="cypress" />
+import 'os';
+
+describe('Login', () => {
+  it('should render the login page', () => {
+    cy.visit('/');
+    cy.contains('Select a sign-in method');
+  });
+
+  it('should be able to login', () => {
+    cy.get('button').contains('Enter').click();
+    cy.url().should('include', '/catalog');
+
+    cy.contains('artist-lookup');
+  });
+});

cypress/src/integration/user/logout.spec.ts

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/// <reference types="cypress" />
+import 'os';
+
+describe('Logout', () => {
+  before(() => {
+    cy.loginAsGuest();
+  });
+  it('should be able to logout', () => {
+    cy.visit('/settings');
+    cy.get('[data-testid="user-settings-menu"]').click();
+    return cy
+      .get('[data-testid="sign-out"]')
+      .click()
+      .then(() => {
+        return expect(
+          localStorage.getItem('@backstage/core:SignInPage:provider'),
+        ).to.be.null;
+      });
+  });
+});

cypress/src/support/commands.ts

@@ -0,0 +1,116 @@
+/*
+ * Copyright 2021 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/* eslint-disable jest/no-standalone-expect */
+/// <reference types="cypress" />
+import 'os';
+
+Cypress.Commands.add('loginAsGuest', () => {
+  cy.visit('/', {
+    onLoad: (win: Window) =>
+      win.localStorage.setItem('@backstage/core:SignInPage:provider', 'guest'),
+  });
+});
+
+Cypress.Commands.add('getTechDocsShadowRoot', () => {
+  cy.get('[data-testid="techdocs-content-shadowroot"]').shadow();
+});
+
+Cypress.Commands.add('isNotInViewport', element => {
+  cy.get(element).then($el => {
+    const bottom = Cypress.config(`viewportHeight`);
+    const rect = $el[0].getBoundingClientRect();
+
+    if (bottom) {
+      expect(rect.top).to.be.greaterThan(bottom);
+      expect(rect.bottom).to.be.greaterThan(bottom);
+      expect(rect.top).to.be.greaterThan(bottom);
+      expect(rect.bottom).to.be.greaterThan(bottom);
+    }
+  });
+});
+
+Cypress.Commands.add('isInViewport', element => {
+  cy.get(element).then($el => {
+    const bottom = Cypress.config(`viewportHeight`);
+    const rect = $el[0].getBoundingClientRect();
+
+    if (bottom) {
+      expect(rect.top).not.to.be.greaterThan(bottom);
+      expect(rect.bottom).not.to.be.greaterThan(bottom);
+      expect(rect.top).not.to.be.greaterThan(bottom);
+      expect(rect.bottom).not.to.be.greaterThan(bottom);
+    }
+  });
+});
+
+Cypress.Commands.add('getTechDocsTableOfContents', () => {
+  cy.get('[data-md-component="toc"]');
+});
+
+Cypress.Commands.add('getTechDocsNavigation', () => {
+  cy.get('[data-md-component="navigation"]');
+});
+
+Cypress.Commands.add('mockSockJSNode', () => {
+  cy.intercept('GET', '**/sockjs-node/info**', {
+    body: {
+      websocket: true,
+      origins: ['*:*'],
+      cookie_needed: false,
+      entropy: 2882389500,
+    },
+  });
+});
+
+Cypress.Commands.add('interceptTechDocsAPICalls', () => {
+  cy.intercept(
+    'GET',
+    '**/techdocs/metadata/entity/default/Component/techdocs-e2e-fixture',
+  ).as('entityMetadata');
+
+  cy.intercept(
+    'GET',
+    '**/techdocs/metadata/techdocs/default/Component/techdocs-e2e-fixture',
+  ).as('techdocsMetadata');
+
+  cy.intercept(
+    'GET',
+    '**/techdocs/sync/default/Component/techdocs-e2e-fixture',
+  ).as('syncEntity');
+
+  cy.intercept(
+    'GET',
+    '**/techdocs/static/docs/default/Component/techdocs-e2e-fixture/sub-page-two/index.html',
+  ).as('sectionTwoHTML');
+
+  cy.intercept(
+    'GET',
+    '**/techdocs/static/docs/default/Component/techdocs-e2e-fixture/index.html',
+  ).as('homeHTML');
+});
+
+Cypress.Commands.add('waitSectionTwoPage', () => {
+  cy.wait([
+    '@entityMetadata',
+    '@syncEntity',
+    '@techdocsMetadata',
+    '@sectionTwoHTML',
+  ]);
+});
+
+Cypress.Commands.add('waitHomePage', () => {
+  cy.wait(['@entityMetadata', '@syncEntity', '@techdocsMetadata', '@homeHTML']);
+});

cypress/src/support/index.ts

@@ -14,12 +14,4 @@
  * limitations under the License.
  */
 /// <reference types="cypress" />
-
-Cypress.Commands.add('loginAsGuest', () => {
-  cy.visit('/', {
-    onLoad: (win: Window) =>
-      win.localStorage.setItem('@backstage/core:SignInPage:provider', 'guest'),
-  });
-});
-
-export {};
+import './commands';

cypress/src/types.d.ts

@@ -22,5 +22,55 @@ declare namespace Cypress {
      * @example cy.loginAsGuests
      */
     loginAsGuest(): Chainable<Element>;
+    /**
+     * Get the TechDocs shadow root element
+     * @example cy.getTechDocsShadowRoot
+     */
+    getTechDocsShadowRoot(): Chainable<Element>;
+    /**
+     * Mock TechDocs backend API
+     * @example cy.mockTechDocs
+     */
+    mockTechDocs(): void;
+    /**
+     * Get the TechDocs table of contents element
+     * @example cy.getTechDocsShadowRoot
+     */
+    getTechDocsTableOfContents(): Chainable<Element>;
+    /**
+     * Get the TechDocs navigation element
+     * @example cy.getTechDocsNavigation
+     */
+    getTechDocsNavigation(): Chainable<Element>;
+    /**
+     * Intercept the TechDocs API calls
+     * @example cy.interceptTechDocsAPICalls
+     */
+    interceptTechDocsAPICalls(): Chainable<Element>;
+    /**
+     * Mock SockJS-Node call
+     * @example cy.mockSockJSNode
+     */
+    mockSockJSNode(): Chainable<Element>;
+    /**
+     * Wait TechDocs API response for home page
+     * @example cy.waitHomePage
+     */
+    waitHomePage(): Chainable<Element>;
+    /**
+     * Wait TechDocs API response for Section 2 page
+     * @example cy.waitSectionTwoPage
+     */
+    waitSectionTwoPage(): Chainable<Element>;
+    /**
+     * Check if the element is in viewport
+     * @example cy.isInViewport
+     */
+    isInViewport(element: string): Chainable<Element>;
+    /**
+     * Check if the element is not in viewport
+     * @example cy.isNotInViewport
+     */
+    isNotInViewport(element: string): Chainable<Element>;
   }
 }

docs/.gitignore

@@ -0,0 +1,2 @@
+# This is generated by build:api-docs in the root
+reference

docs/api/utility-apis.md

@@ -12,25 +12,32 @@ however always be a need for plugins to communicate outside of its boundaries,
 both with other plugins and the app itself.
 
 Backstage provides two primary methods for plugins to communicate across their
-boundaries in client-side code. The first one being the `createPlugin` API and
-the registration hooks passed to the `register` method, and the second one being
-Utility APIs. While the `createPlugin` API is focused on the initialization
-plugins and the app, the Utility APIs provide ways for plugins to communicate
-during their entire life cycle.
+boundaries in client-side code. The first one being the
+[createPlugin](../reference/core-plugin-api.createplugin.md) API along with the
+extensions that it can provide, and the second one being Utility APIs. While the
+[createPlugin](../reference/core-plugin-api.createplugin.md) API is focused on
+the initialization plugins and the app, the Utility APIs provide ways for
+plugins to communicate during their entire life cycle.
 
 ## Consuming APIs
 
-Each Utility API is tied to an `ApiRef` instance, which is a global singleton
-object without any additional state or functionality, its only purpose is to
-reference Utility APIs. `ApiRef`s are created using `createApiRef`, which is
-exported by `@backstage/core-plugin-api`. There are many
-[predefined Utility APIs](../reference/utility-apis/README.md) defined in
-`@backstage/core-plugin-api`, and they're all exported with a name of the
-pattern `*ApiRef`, for example `errorApiRef`.
+Each Utility API is tied to an [ApiRef](../reference/core-plugin-api.apiref.md)
+instance, which is a global singleton object without any additional state or
+functionality, its only purpose is to reference Utility APIs.
+[ApiRef](../reference/core-plugin-api.apiref.md)s are created using
+[createApiRef](../reference/core-plugin-api.createapiref.md), which is exported
+by [@backstage/core-plugin-api](../reference/core-plugin-api.md). There are also
+many predefined Utility APIs in
+[@backstage/core-plugin-api](../reference/core-plugin-api.md), and they're all
+exported with a name of the pattern `*ApiRef`, for example
+[errorApiRef](../reference/core-plugin-api.errorapiref.md).
 
-To access one of the Utility APIs inside a React component, use the `useApi`
-hook exported by `@backstage/core-plugin-api`, or the `withApis` HOC if you
-prefer class components. For example, the `ErrorApi` can be accessed like this:
+To access one of the Utility APIs inside a React component, use the
+[useApi](../reference/core-plugin-api.useapi.md) hook exported by
+[@backstage/core-plugin-api](../reference/core-plugin-api.md), or the
+[withApis](../reference/core-plugin-api.withapis.md) HOC if you prefer class
+components. For example, the
+[ErrorApi](../reference/core-plugin-api.errorapi.md) can be accessed like this:
 
 ```tsx
 import React from 'react';
@@ -48,24 +55,31 @@ export const MyComponent = () => {
 };
 ```
 
-Note that there is no explicit type given for `ErrorApi`. This is because the
-`errorApiRef` has the type embedded, and `useApi` is able to infer the type.
+Note that there is no explicit type given for
+[ErrorApi](../reference/core-plugin-api.errorapi.md). This is because the
+[errorApiRef](../reference/core-plugin-api.errorapiref.md) has the type
+embedded, and [useApi](../reference/core-plugin-api.useapi.md) is able to infer
+the type.
 
 Also note that consuming Utility APIs is not limited to plugins, it can be done
 from any component inside Backstage, including the ones in
-`@backstage/core-plugin-api`. The only requirement is that they are beneath the
-`AppProvider` in the react tree.
+[@backstage/core-plugin-api](../reference/core-plugin-api.md). The only
+requirement is that they are beneath the `AppProvider` in the react tree.
 
 ## Supplying APIs
 
 ### API Factories
 
-APIs are registered in the form of `ApiFactories`, which encapsulate the process
-of instantiating an API. It is a collection of three things: the `ApiRef` of the
-API to instantiate, a list of all required dependencies, and a factory function
-that returns a new API instance.
+APIs are registered in the form of
+[ApiFactories](../reference/core-plugin-api.apifactory.md), which encapsulate
+the process of instantiating an API. It is a collection of three things: the
+[ApiRef](../reference/core-plugin-api.apiref.md) of the API to instantiate, a
+list of all required dependencies, and a factory function that returns a new API
+instance.
 
-For example, this is the default `ApiFactory` for the `ErrorApi`:
+For example, this is the default
+[ApiFactory](../reference/core-plugin-api.apifactory.md) for the
+[ErrorApi](../reference/core-plugin-api.errorapi.md):
 
 ```ts
 createApiFactory({
@@ -79,18 +93,25 @@ createApiFactory({
 });
 ```
 
-In this example the `errorApiRef` is our API, which encapsulates the `ErrorApi`
-type. The `alertApiRef` is our single dependency, which we give the name
-`alertApi`, and is then passed on to the factory function, which returns an
-implementation of the `ErrorApi`.
+In this example the [errorApiRef](../reference/core-plugin-api.errorapiref.md)
+is our API, which encapsulates the
+[ErrorApi](../reference/core-plugin-api.errorapi.md) type. The
+[alertApiRef](../reference/core-plugin-api.alertapiref.md) is our single
+dependency, which we give the name `alertApi`, and is then passed on to the
+factory function, which returns an implementation of the
+[ErrorApi](../reference/core-plugin-api.errorapi.md).
 
-The `createApiFactory` function is a thin wrapper that enables TypeScript type
-inference. You may notice that there are no type annotations in the above
-example, and that is because we're able to infer all types from the `ApiRef`s.
-TypeScript will make sure that the return value of the `factory` function
-matches the type embedded in `api`'s `ApiRef`, in this case the `ErrorApi`. It
-will also match the types between the `deps` and the parameters of the `factory`
-function, again using the type embedded within the `ApiRef`s.
+The [createApiFactory](../reference/core-plugin-api.createapifactory.md)
+function is a thin wrapper that enables TypeScript type inference. You may
+notice that there are no type annotations in the above example, and that is
+because we're able to infer all types from the
+[ApiRef](../reference/core-plugin-api.apiref.md)s. TypeScript will make sure
+that the return value of the `factory` function matches the type embedded in
+`api`'s [ApiRef](../reference/core-plugin-api.apiref.md), in this case the
+[ErrorApi](../reference/core-plugin-api.errorapi.md). It will also match the
+types between the `deps` and the parameters of the `factory` function, again
+using the type embedded within the
+[ApiRef](../reference/core-plugin-api.apiref.md)s.
 
 ## Registering API Factories
 
@@ -102,24 +123,27 @@ app, and the app itself.
 
 Starting with the Backstage core library, it provides implementations for all of
 the core APIs. The core APIs are the ones exported by
-`@backstage/core-plugin-api`, such as the `errorApiRef` and `configApiRef`. You
-can find a full list of them [here](../reference/utility-apis/README.md).
+[@backstage/core-plugin-api](../reference/core-plugin-api.md), such as the
+[errorApiRef](../reference/core-plugin-api.errorapiref.md) and
+[configApiRef](../reference/core-plugin-api.configapiref.md).
 
-The core APIs are loaded for any app created with `createApp` from
-`@backstage/core-plugin-api`, which means that there is no step that needs to be
-taken to include these APIs in an app.
+The core APIs are loaded for any app created with
+[createApp](../reference/core-app-api.createapp.md) from
+[@backstage/core-plugin-api](../reference/core-plugin-api.md), which means that
+there is no step that needs to be taken to include these APIs in an app.
 
 ### Plugin APIs
 
 In addition to the core APIs, plugins can define and export their own APIs.
 While doing so they should usually also provide default implementations of their
 own APIs, for example, the `catalog` plugin exports `catalogApiRef`, and also
-supplies a default `ApiFactory` of that API using the `CatalogClient`. There is
-one restriction to plugin-provided API Factories: plugins may not supply
-factories for core APIs, trying to do so will cause the app to refuse to start.
+supplies a default [ApiFactory](../reference/core-plugin-api.apifactory.md) of
+that API using the `CatalogClient`. There is one restriction to plugin-provided
+API Factories: plugins may not supply factories for core APIs, trying to do so
+will cause the app to refuse to start.
 
-Plugins supply their APIs through the `apis` option of `createPlugin`, for
-example:
+Plugins supply their APIs through the `apis` option of
+[createPlugin](../reference/core-plugin-api.createplugin.md), for example:
 
 ```ts
 export const techdocsPlugin = createPlugin({
@@ -144,7 +168,8 @@ Lastly, the app itself is the final point where APIs can be added, and what has
 the final say in what APIs will be loaded at runtime. The app may override the
 factories for any of the core or plugin APIs, with the exception of the config,
 app theme, and identity APIs. These are static APIs that are tied into the
-`createApp` implementation, and therefore not possible to override.
+[createApp](../reference/core-app-api.createapp.md) implementation, and
+therefore not possible to override.
 
 Overriding APIs is useful for apps that want to switch out behavior to tailor it
 to their environment. In some cases plugins may also export multiple
@@ -206,16 +231,19 @@ const app = createApp({
 ```
 
 Note that the above line will cause an error if `IgnoreErrorApi` does not fully
-implement the `ErrorApi`, as it is checked by the type embedded in the
-`errorApiRef` at compile time.
+implement the [ErrorApi](../reference/core-plugin-api.errorapi.md), as it is
+checked by the type embedded in the
+[errorApiRef](../reference/core-plugin-api.errorapiref.md) at compile time.
 
 ## Defining custom Utility APIs
 
 Plugins are free to define their own Utility APIs. Simply define the TypeScript
-interface for the API, and create an `ApiRef` using `createApiRef` exported from
-`@backstage/core-plugin-api`. Also be sure to provide at least one
-implementation of the API, and to declare a default factory for the API in
-`createPlugin`.
+interface for the API, and create an
+[ApiRef](../reference/core-plugin-api.apiref.md) using
+[createApiRef](../reference/core-plugin-api.createapiref.md) exported from
+[@backstage/core-plugin-api](../reference/core-plugin-api.md). Also be sure to
+provide at least one implementation of the API, and to declare a default factory
+for the API in [createPlugin](../reference/core-plugin-api.createplugin.md).
 
 Custom Utility APIs can be either public or private, which is up to the plugin
 to choose. Private APIs do not expose an external API surface, and it's
@@ -226,15 +254,18 @@ plugin to override the API in the app. It is however important to maintain
 backwards compatibility of public APIs, as you may otherwise break apps that are
 using your plugin.
 
-To make an API public, simply export the `ApiRef` of the API, and any associated
-types. To make an API private, just avoid exporting the `ApiRef`, but still be
-sure to supply a default factory to `createPlugin`.
+To make an API public, simply export the
+[ApiRef](../reference/core-plugin-api.apiref.md) of the API, and any associated
+types. To make an API private, just avoid exporting the
+[ApiRef](../reference/core-plugin-api.apiref.md), but still be sure to supply a
+default factory to [createPlugin](../reference/core-plugin-api.createplugin.md).
 
 Private APIs are useful for plugins that want to depend on other APIs outside of
 React components, but not have to expose an entire API surface to maintain. When
 using private APIs, it is fine to use the `typeof` of an implementing class as
-the type parameter passed to `createApiRef`, while public APIs should always
-define a separate TypeScript interface type.
+the type parameter passed to
+[createApiRef](../reference/core-plugin-api.createapiref.md), while public APIs
+should always define a separate TypeScript interface type.
 
 Plugins may depend on APIs from other plugins, both in React components and as
 dependencies to API factories. Do however be sure to not cause circular
@@ -242,13 +273,14 @@ dependencies between plugins.
 
 ## Architecture
 
-The `ApiRef` instances mentioned above provide a point of indirection between
-consumers and producers of Utility APIs. It allows for plugins and components to
-depend on APIs in a type-safe way, without having a direct reference to a
-concrete implementation of the APIs. The Apps are also given a lot of
-flexibility in what implementations to provide. As long as they adhere to the
-contract established by an `ApiRef`, they are free to choose any implementation
-they want.
+The [ApiRef](../reference/core-plugin-api.apiref.md) instances mentioned above
+provide a point of indirection between consumers and producers of Utility APIs.
+It allows for plugins and components to depend on APIs in a type-safe way,
+without having a direct reference to a concrete implementation of the APIs. The
+Apps are also given a lot of flexibility in what implementations to provide. As
+long as they adhere to the contract established by an
+[ApiRef](../reference/core-plugin-api.apiref.md), they are free to choose any
+implementation they want.
 
 The figure below shows the relationship between
 <span style="color: #82b366">different Apps</span>, that provide
@@ -271,14 +303,17 @@ directly tied to React.
 The indirection provided by Utility APIs also makes it straightforward to test
 components that depend on APIs, and to provide a standard common development
 environment for plugins. A proper test wrapper with mocked API implementations
-is not yet ready, but it will be provided as a part of `@backstage/test-utils`.
-It will provide mocked variants of APIs, with additional methods for asserting a
-component's interaction with the API.
+is not yet ready, but it will be provided as a part of
+[@backstage/test-utils](../reference/test-utils.md). It will provide mocked
+variants of APIs, with additional methods for asserting a component's
+interaction with the API.
 
 The common development environment for plugins is included in
-`@backstage/dev-utils`, where the exported `createDevApp` function creates an
+[@backstage/dev-utils](../reference/dev-utils.md), where the exported
+[createDevApp](../reference/dev-utils.createdevapp.md) function creates an
 application with implementations for all core APIs already present. Contrary to
 the method for wiring up Utility API implementations in an app created with
-`createApp`, `createDevApp` uses automatic dependency injection. This is to make
-it possible to replace any API implementation, and having that be reflected in
-dependents of that API.
+[createApp](../reference/core-app-api.createapp.md),
+[createDevApp](../reference/dev-utils.createdevapp.md) uses automatic dependency
+injection. This is to make it possible to replace any API implementation, and
+having that be reflected in dependents of that API.