Merge branch 'master' of github.com:spotify/backstage into adds_auth0

2020-08-17 13:29:15 +02:00
parent 033233d81f 364d4b3d7a
commit 981e66d553
301 changed files with 10005 additions and 7737 deletions
@@ -2,13 +2,9 @@ name: CLI Test

 on:
  pull_request:
-    paths:
-      - '.github/workflows/cli.yml'
-      - 'packages/cli/**'
-      - 'packages/create-app/**'
-      - 'packages/core/**'
-      - 'packages/core-api/**'
-      - 'yarn.lock'
+    paths-ignore:
+      - 'microsite/**'
+

 jobs:
  build:
@@ -2,8 +2,8 @@ name: Frontend CI

 on:
  pull_request:
-    paths:
-      - '!microsite/**'
+    paths-ignore:
+      - 'microsite/**'
 jobs:
  build:
    runs-on: ubuntu-latest
@@ -45,12 +45,12 @@ jobs:
        run: git diff --quiet origin/master HEAD -- yarn.lock
        continue-on-error: true

-      - name: verify doc links
-        run: node docs/verify-links.js
-
      - name: yarn install
        run: yarn install --frozen-lockfile

+      - name: verify doc links
+        run: node docs/verify-links.js
+
      - name: lint
        run: yarn lerna -- run lint --since origin/master

@@ -0,0 +1,52 @@
+name: Build microsite
+
+on:
+  pull_request:
+    paths:
+      - '.github/workflows/microsite-build-check.yml'
+      - 'microsite/**'
+      - 'docs/**'
+
+jobs:
+  build-microsite:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [12.x]
+
+    env:
+      CI: true
+      NODE_OPTIONS: --max-old-space-size=4096
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: find location of global yarn cache
+        id: yarn-cache
+        run: echo "::set-output name=dir::$(yarn cache dir)"
+
+      - name: cache global yarn cache
+        uses: actions/cache@v2
+        with:
+          path: ${{ steps.yarn-cache.outputs.dir }}
+          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-yarn-
+
+      - name: cache node_modules
+        uses: actions/cache@v2
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-modules-${{ hashFiles('yarn.lock') }}
+
+      - 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: yarn install
+        run: yarn install --frozen-lockfile
+
+      - name: build microsite
+        run: yarn workspace backstage-microsite build
@@ -1,16 +1,17 @@
-name: Deploy Storybook
+name: Deploy Microsite and Storybook

 on:
  push:
    branches:
      - master
    paths:
-      - '.github/workflows/storybook-deploy.yml'
+      - '.github/workflows/microsite-with-storybook-deploy.yml'
      - 'packages/storybook/**'
      - 'packages/core/src/**'
+      - 'microsite/**'

 jobs:
-  deploy-storybook:
+  deploy-microsite-and-storybook:
    runs-on: ubuntu-latest

    strategy:
@@ -26,6 +27,7 @@ jobs:
      - name: find location of global yarn cache
        id: yarn-cache
        run: echo "::set-output name=dir::$(yarn cache dir)"
+
      - name: cache global yarn cache
        uses: actions/cache@v2
        with:
@@ -33,6 +35,7 @@ jobs:
          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
          restore-keys: |
            ${{ runner.os }}-yarn-
+
      - name: cache node_modules
        uses: actions/cache@v2
        with:
@@ -44,13 +47,25 @@ jobs:
        with:
          node-version: ${{ matrix.node-version }}
          registry-url: https://registry.npmjs.org/ # Needed for auth
+
      - name: yarn install
        run: yarn install --frozen-lockfile
+
+      - name: build microsite
+        run: yarn workspace backstage-microsite build
+
      - name: build storybook
        run: yarn workspace storybook build-storybook
-      - name: deploy storybook to gh-pages
+
+      - name: move storybook dist into microsite
+        run: mv packages/storybook/dist/ microsite/build/backstage/storybook
+
+      - name: Check the build output
+        run: ls microsite/build/backstage && ls microsite/build/backstage/storybook
+
+      - name: Deploy both microsite and storybook to gh-pages
        uses: JamesIves/github-pages-deploy-action@3.4.2
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          BRANCH: gh-pages
-          FOLDER: packages/storybook/dist
+          FOLDER: microsite/build/backstage
@@ -90,6 +90,9 @@ typings/
 .nuxt
 dist

+# Microsite build output
+microsite/build
+
 # Gatsby files
 .cache/
 # Comment in the public line in if your project uses Gatsby and not Next.js
@@ -8,6 +8,18 @@ If you encounter issues while upgrading to a newer version, don't hesitate to re

 > Collect changes for the next release below

+### @backstage/create-app
+
+- Many plugins have been added to the catalog and will for now be required to be added to separate apps as well. This will be solved as [#1536](https://github.com/spotify/backstage/issues/1536) gets sorted out, but for now you may need to install some plugins just to get pages to work.
+
+### @backstage/catalog-backend
+
+- Added the possibility to add static locations via `app-config.yaml`. This changed the signature of `new LocationReaders(logger)` inside `packages/backend/src/plugins/catalog.ts` to `new LocationReaders({config, logger})`. [#1890](https://github.com/spotify/backstage/pull/1890)
+
+### @backstage/theme
+
+- Changed the type signature of the palette, removing `sidebar: string` and adding `navigation: { background: string; indicator: string}`. [#1880](https://github.com/spotify/backstage/pull/1880)
+
 ## v0.1.1-alpha.18

 ### @backstage/catalog-backend
@@ -1,4 +1,7 @@
-# Contributing
+---
+id: CONTRIBUTING
+title: Contributing
+---

 Our vision for Backstage is for it to become the trusted standard toolbox (read: UX layer) for the open source infrastructure landscape. Think of it like Kubernetes for developer experience. We realize this is an ambitious goal. We can’t do it alone.

@@ -38,7 +41,7 @@ The current documentation is very limited. Help us make the `/docs` folder come

 ## Contribute to Storybook

-We think the best way to ensure different plugins provide a consistent experience is through a solid set of reusable UI/UX components. Backstage uses [Storybook](http://storybook.backstage.io).
+We think the best way to ensure different plugins provide a consistent experience is through a solid set of reusable UI/UX components. Backstage uses [Storybook](http://backstage.io/storybook).

 Either help us [create new components](https://github.com/spotify/backstage/labels/help%20wanted) or improve stories for the existing ones (look for files with `*.stories.tsx`).

@@ -60,7 +63,35 @@ Have you started using Backstage? Adding your company to [ADOPTERS](ADOPTERS.md)

 # Get Started!

-So...feel ready to jump in? Let's do this. Head over to the [Getting Started guide](https://github.com/spotify/backstage#getting-started) 👏🏻💯
+So...feel ready to jump in? Let's do this. 👏🏻💯
+
+To run a Backstage app, you will need to have the following installed:
+
+- [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+- [NodeJS](https://nodejs.org/en/download/) - Active LTS Release, currently v12
+- [yarn](https://classic.yarnpkg.com/en/docs/install)
+
+After cloning this repo, open a terminal window and start the example app using the following commands from the project root:
+
+```bash
+yarn install # Install dependencies
+
+yarn start # Start dev server, use --check to enable linting and type-checks
+```
+
+The final `yarn start` command should open a local instance of Backstage in your browser, otherwise open one of the URLs printed in the terminal.
+
+Depending on the work you're doing, you often also want to run the example backend. Start the backend in a separate terminal session using the following:
+
+```bash
+cd packages/backend
+
+yarn start
+
+yarn lerna run mock-data # Populate the backend with mock data
+```
+
+And that's it! You are good to go 👍

 If you need help, just jump into our [Discord chatroom](https://discord.gg/MUpMjP2).

@@ -1,4 +1,4 @@
-![headline](docs/headline.png)
+![headline](docs/assets/headline.png)

 # [Backstage](https://backstage.io)

@@ -29,7 +29,7 @@ For more information go to [backstage.io](https://backstage.io) or join our [Dis

 We created Backstage about 4 years ago. While our internal version of Backstage has had the benefit of time to mature and evolve, the first iteration of our open source version is still nascent. We are envisioning three phases of the project and we have already begun work on various aspects of these phases:

- 🐣 **Phase 1:** Extensible frontend platform (Done ✅) - You will be able to easily create a single consistent UI layer for your internal infrastructure and tools. A set of reusable [UX patterns and components](http://storybook.backstage.io) help ensure a consistent experience between tools.
+- 🐣 **Phase 1:** Extensible frontend platform (Done ✅) - You will be able to easily create a single consistent UI layer for your internal infrastructure and tools. A set of reusable [UX patterns and components](http://backstage.io/storybook) help ensure a consistent experience between tools.

 - 🐢 **Phase 2:** Service Catalog ([alpha released](https://backstage.io/blog/2020/06/22/backstage-service-catalog-alpha)) - With a single catalog, Backstage makes it easy for a team to manage ten services — and makes it possible for your company to manage thousands of them. Developers can get a uniform overview of all their software and related resources, regardless of how and where they are running, as well as an easy way to onboard and manage those resources.

@@ -49,27 +49,33 @@ The Backstage platform consists of a number of different components:
 - [**proxy**](https://github.com/spotify/backstage/tree/master/plugins/proxy-backend) - Terminates HTTPS and exposes any RESTful API to Plugins.
 - **identity** - A backend service that holds your organisation's metadata.

-## Getting started
+## Getting Started

-To run a Backstage app, you will need to have the following installed:
+There are two different ways to get started with Backstage, either by creating a standalone app, or by cloning this repo. Which method you use depends on what you're planning to do.

- [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
- [NodeJS](https://nodejs.org/en/download/) - Active LTS Release, currently v12
- [yarn](https://classic.yarnpkg.com/en/docs/install)
+Creating a standalone instance makes it simpler to customize the application for your needs whilst staying up to date with the project. You will also depend on `@backstage` packages from NPM, making the project much smaller. This is the recommended approach if you want to kick the tyres of Backstage or setup your own instance.

-After cloning this repo, open a terminal window and start the example app using the following commands from the project root:
+On the other hand, if you want to contribute plugins or to the project in general, it's easier to fork and clone this project. That will let you stay up to date with the latest changes, and gives you an easier path to make Pull Requests towards this repo.
+
+### Creating a Standalone App
+
+Backstage provides the `@backstage/create-app` package to scaffold standalone instances of Backstage. You will need to have
+[NodeJS](https://nodejs.org/en/download/) Active LTS Release installed
+(currently v12), and [yarn](https://classic.yarnpkg.com/en/docs/install). You will also need to have [Docker](https://docs.docker.com/engine/install/) installed to use some features like Software Templates and TechDocs.
+
+Using `npx` you can then run the following to create an app in a chosen subdirectory of your current working directory:

 ```bash
-yarn install # Install dependencies
-
-yarn start # Start dev server, use --check to enable linting and type-checks
+npx @backstage/create-app
 ```

-The final `yarn start` command should open a local instance of Backstage in your browser, otherwise open one of the URLs printed in the terminal.
+You will be taken through a wizard to create your app, and the output should look something like this. You can read more about this process [here](docs/getting-started/create-an-app.md)

-And that's it! You are good to go 👍
+### Contributing to Backstage

-### Next step
+You can read more in our [CONTRIBUTING.md](./CONTRIBUTING.md#get-started) guide, which can help you get setup with a Backstage development environment.
+
+### Next steps

 Take a look at the [Getting Started](docs/getting-started/index.md) guide to learn how to set up Backstage, and how to develop on the platform.

@@ -77,14 +83,9 @@ Take a look at the [Getting Started](docs/getting-started/index.md) guide to lea

 - [Main documentation](docs/README.md)
 - [Service Catalog](docs/features/software-catalog/index.md)
- [Create a Backstage App](docs/getting-started/create-an-app.md)
 - [Architecture](docs/overview/architecture-terminology.md) ([Decisions](docs/architecture-decisions/index.md))
 - [Designing for Backstage](docs/dls/design.md)
- [Storybook - UI components](http://storybook.backstage.io)
-
-## Contributing
-
-We would love your help in building Backstage! See [CONTRIBUTING](CONTRIBUTING.md) for more information.
+- [Storybook - UI components](http://backstage.io/storybook)

 ## Community

@@ -4,11 +4,15 @@ app:

 backend:
  baseUrl: http://localhost:7000
-  listen: 0.0.0.0:7000
+  listen:
+    port: 7000
  cors:
    origin: http://localhost:3000
    methods: [GET, POST, PUT, DELETE]
    credentials: true
+  database:
+    client: sqlite3
+    connection: ':memory:'

 proxy:
  '/circleci/api':
@@ -16,6 +20,15 @@ proxy:
    changeOrigin: true
    pathRewrite:
      '^/proxy/circleci/api/': '/'
+  '/jenkins/api':
+    target: 'http://localhost:8080'
+    changeOrigin: true
+    headers:
+      Authorization:
+        $secret:
+          env: JENKINS_BASIC_AUTH_HEADER
+    pathRewrite:
+      '^/proxy/jenkins/api/': '/'

 organization:
  name: Spotify
@@ -26,6 +39,17 @@ techdocs:
 sentry:
  organization: spotify

+rollbar:
+  organization: spotify
+  accountToken:
+    $secret:
+      env: ROLLBAR_ACCOUNT_TOKEN
+
+newrelic:
+  api:
+    baseUrl: 'https://api.newrelic.com/v2'
+    key: NEW_RELIC_REST_API_KEY
+
 auth:
  providers:
    google:
@@ -1,4 +1,7 @@
-# FAQ
+---
+id: FAQ
+title: FAQ
+---

 ## Product FAQ:

@@ -14,8 +17,7 @@ brand.
 No, but it can be! Backstage is designed to be a developer portal for all your
 infrastructure tooling, services, and documentation. So, it's not a monitoring
 platform — but that doesn't mean you can't integrate a monitoring tool into
-Backstage by writing
-[a plugin](/docs/FAQ.md#what-is-a-plugin-in-backstage).
+Backstage by writing [a plugin](#what-is-a-plugin-in-backstage).

 ### How is Backstage licensed?

@@ -36,12 +38,11 @@ more, read our blog post,

 Yes, we've already started releasing open source versions of some of the plugins
 we use here, and we'll continue to do so.
-[Plugins](/docs/FAQ.md#what-is-a-plugin-in-backstage) are the
-building blocks of functionality in Backstage. We have over 120 plugins inside
-Spotify — many of those are specialized for our use, so will remain internal and
-proprietary to us. But we estimate that about a third of our existing plugins
-make good open source candidates. (And we'll probably end up writing some brand
-new ones, too.)
+[Plugins](#what-is-a-plugin-in-backstage) are the building blocks of
+functionality in Backstage. We have over 120 plugins inside Spotify — many of
+those are specialized for our use, so will remain internal and proprietary to
+us. But we estimate that about a third of our existing plugins make good open
+source candidates. (And we'll probably end up writing some brand new ones, too.)

 ### What's the roadmap for Backstage?

@@ -91,21 +92,31 @@ Node.js and GraphQL.
 ### What is the end-to-end user flow? The happy path story.

 There are three main user profiles for Backstage: the integrator, the
-contributor, and the software engineer. 
+contributor, and the software engineer.

-The **integrator** hosts the Backstage app and configures which plugins are available to use in the app. 
+The **integrator** hosts the Backstage app and configures which plugins are
+available to use in the app.

 The **contributor** adds functionality to the app by writing plugins.

-The **software engineer** uses the app's functionality and interacts with its plugins.
+The **software engineer** uses the app's functionality and interacts with its
+plugins.

 ### What is a "plugin" in Backstage?

-Plugins are what provide the feature functionality in Backstage. They are used to integrate different systems into Backstage's frontend, so that the developer gets a consistent UX, no matter what tool or service is being accessed on the other side.
+Plugins are what provide the feature functionality in Backstage. They are used
+to integrate different systems into Backstage's frontend, so that the developer
+gets a consistent UX, no matter what tool or service is being accessed on the
+other side.

-Each plugin is treated as a self-contained web app and can include almost any type of content. Plugins all use a common set of platform APIs and reusable UI components. Plugins can fetch data either from the backend or an API exposed through the proxy.
+Each plugin is treated as a self-contained web app and can include almost any
+type of content. Plugins all use a common set of platform APIs and reusable UI
+components. Plugins can fetch data either from the backend or an API exposed
+through the proxy.

-Learn more about [the different components](https://github.com/spotify/backstage#overview) that make up Backstage.
+Learn more about
+[the different components](https://github.com/spotify/backstage#overview) that
+make up Backstage.

 ### Do I have to write plugins in TypeScript?

@@ -127,7 +138,15 @@ can browse and search for all available plugins.

 ### Which plugin is used the most at Spotify?

-By far, our most-used plugin is our TechDocs plugin, which we use for creating technical documentation. Our philosophy at Spotify is to treat "docs like code", where you write documentation using the same workflow as you write your code. This makes it easier to create, find, and update documentation. We hope to release [the open source version](https://github.com/spotify/backstage/issues/687) in the future. (See also: "[Will Spotify's internal plugins be open sourced, too?](/docs/FAQ.md#will-spotifys-internal-plugins-be-open-sourced-too)" above)
+By far, our most-used plugin is our TechDocs plugin, which we use for creating
+technical documentation. Our philosophy at Spotify is to treat "docs like code",
+where you write documentation using the same workflow as you write your code.
+This makes it easier to create, find, and update documentation. We hope to
+release
+[the open source version](https://github.com/spotify/backstage/issues/687) in
+the future. (See also:
+"[Will Spotify's internal plugins be open sourced, too?](#will-spotifys-internal-plugins-be-open-sourced-too)"
+above)

 ### Are you planning to have plugins baked into the repo? Or should they be developed in separate repos?

@@ -135,10 +154,10 @@ Contributors can add open source plugins to the plugins directory in
 [this monorepo](https://github.com/spotify/backstage). Integrators can then
 configure which open source plugins are available to use in their instance of
 the app. Open source plugins are downloaded as npm packages published in the
-open source repository. While we encourage using the open source model, we
-know there are cases where contributors might want to experiment internally or
-keep their plugins closed source. Contributors writing closed source plugins
-should develop them in the plugins directory in their own Backstage repository.
+open source repository. While we encourage using the open source model, we know
+there are cases where contributors might want to experiment internally or keep
+their plugins closed source. Contributors writing closed source plugins should
+develop them in the plugins directory in their own Backstage repository.
 Integrators also configure closed source plugins locally from the monorepo.

 ### Any plans for integrating with other repository managers, such as GitLab or Bitbucket?
@@ -149,7 +168,8 @@ stage. Hosting this project on GitHub does not exclude integrations with
 alternatives, such as
 [GitLab](https://github.com/spotify/backstage/issues?q=is%3Aissue+is%3Aopen+GitLab)
 or Bitbucket. We believe that in time there will be plugins that will provide
-functionality for these tools as well. Hopefully, contributed by the community! Also note, implementations of Backstage can be hosted wherever you feel suits
+functionality for these tools as well. Hopefully, contributed by the community!
+Also note, implementations of Backstage can be hosted wherever you feel suits
 your needs best.

 ### Who maintains Backstage?
@@ -165,8 +185,8 @@ maintains Backstage in your own environment.

 ### Does Spotify provide a managed version of Backstage?

-No, this is not a service offering. We build the piece of software, and
-someone in your infrastructure team is responsible for
+No, this is not a service offering. We build the piece of software, and someone
+in your infrastructure team is responsible for
 [deploying](https://github.com/spotify/backstage/blob/master/DEPLOYMENT.md) and
 maintaining it.

@@ -186,16 +206,16 @@ Please report sensitive security issues via Spotify's
 No. Backstage does not collect any telemetry from any third party using the
 platform. Spotify, and the open source community, does have access to
 [GitHub Insights](https://github.com/features/insights), which contains
-information such as contributors, commits, traffic, and dependencies. 
-Backstage is an open platform, but you are in control of your own data. You
-control who has access to any data you provide to your version of Backstage and
-who that data is shared with.
+information such as contributors, commits, traffic, and dependencies. Backstage
+is an open platform, but you are in control of your own data. You control who
+has access to any data you provide to your version of Backstage and who that
+data is shared with.

 ### Can Backstage be used to build something other than a developer portal?

-Yes. The core frontend framework could be used for building any large-scale
-web application where (1) multiple teams are building separate parts of the app,
-and (2) you want the overall experience to be consistent. That being said, in
+Yes. The core frontend framework could be used for building any large-scale web
+application where (1) multiple teams are building separate parts of the app, and
+(2) you want the overall experience to be consistent. That being said, in
 [Phase 2](https://github.com/spotify/backstage#project-roadmap) of the project
 we will add features that are needed for developer portals and systems for
 managing software ecosystems. Our ambition will be to keep Backstage modular.
@@ -4,99 +4,100 @@
 really 😆) you find broken links or missing content, please create an issue or,
 better yet, a pull request.

+# Plugins
+
 - Overview
  - [What is Backstage?](overview/what-is-backstage.md)
  - [Backstage architecture](overview/architecture-overview.md)
  - [Architecture and terminology](overview/architecture-terminology.md)
  - [Roadmap](overview/roadmap.md)
-  - Getting started
-    - [Running Backstage locally](getting-started/index.md)
-    - [Installation](getting-started/installation.md)
-    - [Local development](getting-started/development-environment.md)
-    - [Demo deployment](https://backstage-demo.roadie.io)
-    - Production deployments
-      - [Create an App](getting-started/create-an-app.md)
-      - App configuration
-        - [Configuring App with plugins](getting-started/configure-app-with-plugins.md)
-        - [Customize the look-and-feel of your App](getting-started/app-custom-theme.md)
-      - Deployment scenarios
-        - [Kubernetes](getting-started/deployment-k8s.md)
-        - [Other](getting-started/deployment-other.md)
-  - Features
-    - Software Catalog
-      - [Overview](features/software-catalog/index.md)
-      - [System model](features/software-catalog/system-model.md)
-      - [YAML File Format](features/software-catalog/descriptor-format.md)
-      - [Populating the catalog](features/software-catalog/populating.md)
-      - [Extending the model](features/software-catalog/extending-the-model.md)
-      - [External integrations](features/software-catalog/external-integrations.md)
-      - [API](features/software-catalog/api.md)
-    - Software creation templates
-      - [Overview](features/software-templates/index.md)
-      - [Adding templates](features/software-templates/adding-templates.md)
-        - Extending the Scaffolder:
-          - [Overview](features/software-templates/extending/index.md)
-          - [Create your own Templater](features/software-templates/extending/create-your-own-templater.md)
-          - [Create your own Publisher](features/software-templates/extending/create-your-own-publisher.md)
-          - [Create your own Preparer](features/software-templates/extending/create-your-own-preparer.md)
-    - Docs-like-code
-      - [Overview](features/techdocs/README.md)
-      - [Getting Started](features/techdocs/getting-started.md)
-      - [Concepts](features/techdocs/concepts.md)
-      - [Creating and Publishing Documentation](features/techdocs/creating-and-publishing.md)
-      - [FAQ](features/techdocs/FAQ.md)
-  - Plugins
-    - [Overview](plugins/index.md)
-    - [Existing plugins](plugins/existing-plugins.md)
-    - [Creating a new plugin](plugins/create-a-plugin.md)
-    - [Developing a plugin](plugins/plugin-development.md)
-    - [Structure of a plugin](plugins/structure-of-a-plugin.md)
-    - Backends and APIs
-      - [Proxying](plugins/proxying.md)
-      - [Backstage backend plugin](plugins/backend-plugin.md)
-      - [Call existing API](plugins/call-existing-api.md)
-    - Testing
-      - [Overview](plugins/testing.md)
-    - Publishing
-      - [Open source and NPM](plugins/publishing.md)
-      - [Private/internal (non-open source)](plugins/publish-private.md)
-  - Configuration
-    - [Overview](conf/index.md)
-    - [Reading Configuration](conf/reading.md)
-    - [Writing Configuration](conf/writing.md)
-    - [Defining Configuration](conf/defining.md)
-  - Authentication and identity
-    - [Overview](auth/index.md)
-    - [Add auth provider](auth/add-auth-provider.md)
-    - [Auth backend](auth/auth-backend.md)
-    - [OAuth](auth/oauth.md)
-    - [Glossary](auth/glossary.md)
-  - Designing for Backstage
-    - [Backstage Design Language System (DLS)](dls/design.md)
-    - [Storybook -- reusable UI components](http://storybook.backstage.io)
-    - [Contributing to Storybook](dls/contributing-to-storybook.md)
-    - [Figma resources](dls/figma.md)
-  - API references
-    - TypeScript API
-      - [Utility APIs](api/utility-apis.md)
-      - [Utility API References](reference/utility-apis/README.md)
-      - [createPlugin](reference/createPlugin.md)
-      - [createPlugin-feature-flags](reference/createPlugin-feature-flags.md)
-      - [createPlugin-router](reference/createPlugin-router.md)
-    - Backend APIs
-      - [Backend](api/backend.md)
-  - Tutorials
-    - [Overview](tutorials/index.md)
-  - Architecture Decision Records (ADRs)
-    - [Overview](architecture-decisions/index.md)
-    - [ADR001 - Architecture Decision Record (ADR) log](architecture-decisions/adr001-add-adr-log.md)
-    - [ADR002 - Default Software Catalog File Format](architecture-decisions/adr002-default-catalog-file-format.md)
-    - [ADR003 - Avoid Default Exports and Prefer Named Exports](architecture-decisions/adr003-avoid-default-exports.md)
-    - [ADR004 - Module Export Structure](architecture-decisions/adr004-module-export-structure.md)
-    - [ADR005 - Catalog Core Entities](architecture-decisions/adr005-catalog-core-entities.md)
-    - [ADR006 - Avoid React.FC and React.SFC](architecture-decisions/adr006-avoid-react-fc.md)
-    - [ADR007 - Use MSW for Mocking Network Requests](architecture-decisions/adr007-use-msw-to-mock-service-requests.md)
-    - [ADR008 - Default Catalog File Name](architecture-decisions/adr008-default-catalog-file-name.md)
-  - [Contribute](../CONTRIBUTING.md)
-  - [Support](overview/support.md)
-  - [FAQ](FAQ.md)
+- Getting started
+  - [Running Backstage locally](getting-started/index.md)
+  - [Installation](getting-started/installation.md)
+  - [Local development](getting-started/development-environment.md)
+  - [Demo deployment](https://backstage-demo.roadie.io)
+  - Production deployments
+    - [Create an App](getting-started/create-an-app.md)
+    - App configuration
+      - [Configuring App with plugins](getting-started/configure-app-with-plugins.md)
+      - [Customize the look-and-feel of your App](getting-started/app-custom-theme.md)
+    - Deployment scenarios
+      - [Kubernetes](getting-started/deployment-k8s.md)
+      - [Other](getting-started/deployment-other.md)
+- Features
+  - Software Catalog
+    - [Overview](features/software-catalog/index.md)
+    - [System model](features/software-catalog/system-model.md)
+    - [YAML File Format](features/software-catalog/descriptor-format.md)
+    - [Extending the model](features/software-catalog/extending-the-model.md)
+    - [External integrations](features/software-catalog/external-integrations.md)
+    - [API](features/software-catalog/api.md)
+  - Software creation templates
+    - [Overview](features/software-templates/index.md)
+    - [Adding templates](features/software-templates/adding-templates.md)
+      - Extending the Scaffolder:
+        - [Overview](features/software-templates/extending/index.md)
+        - [Create your own Templater](features/software-templates/extending/create-your-own-templater.md)
+        - [Create your own Publisher](features/software-templates/extending/create-your-own-publisher.md)
+        - [Create your own Preparer](features/software-templates/extending/create-your-own-preparer.md)
+  - Docs-like-code
+    - [Overview](features/techdocs/README.md)
+    - [Getting Started](features/techdocs/getting-started.md)
+    - [Concepts](features/techdocs/concepts.md)
+    - [Creating and Publishing Documentation](features/techdocs/creating-and-publishing.md)
+    - [FAQ](features/techdocs/FAQ.md)
+- Plugins
+  - [Overview](plugins/index.md)
+  - [Existing plugins](plugins/existing-plugins.md)
+  - [Creating a new plugin](plugins/create-a-plugin.md)
+  - [Developing a plugin](plugins/plugin-development.md)
+  - [Structure of a plugin](plugins/structure-of-a-plugin.md)
+  - Backends and APIs
+    - [Proxying](plugins/proxying.md)
+    - [Backstage backend plugin](plugins/backend-plugin.md)
+    - [Call existing API](plugins/call-existing-api.md)
+  - Testing
+    - [Overview](plugins/testing.md)
+  - Publishing
+    - [Open source and NPM](plugins/publishing.md)
+    - [Private/internal (non-open source)](plugins/publish-private.md)
+- Configuration
+  - [Overview](conf/index.md)
+  - [Reading Configuration](conf/reading.md)
+  - [Writing Configuration](conf/writing.md)
+  - [Defining Configuration](conf/defining.md)
+- Authentication and identity
+  - [Overview](auth/index.md)
+  - [Add auth provider](auth/add-auth-provider.md)
+  - [Auth backend](auth/auth-backend.md)
+  - [OAuth](auth/oauth.md)
+  - [Glossary](auth/glossary.md)
+- Designing for Backstage
+  - [Backstage Design Language System (DLS)](dls/design.md)
+  - [Storybook -- reusable UI components](http://backstage.io/storybook)
+  - [Contributing to Storybook](dls/contributing-to-storybook.md)
+  - [Figma resources](dls/figma.md)
+- API references
+  - TypeScript API
+    - [Utility APIs](api/utility-apis.md)
+    - [Utility API References](reference/utility-apis/README.md)
+    - [createPlugin](reference/createPlugin.md)
+    - [createPlugin-feature-flags](reference/createPlugin-feature-flags.md)
+    - [createPlugin-router](reference/createPlugin-router.md)
+  - Backend APIs
+    - [Backend](api/backend.md)
+- Tutorials
+  - [Overview](tutorials/index.md)
+- Architecture Decision Records (ADRs)
+  - [Overview](architecture-decisions/index.md)
+  - [ADR001 - Architecture Decision Record (ADR) log](architecture-decisions/adr001-add-adr-log.md)
+  - [ADR002 - Default Software Catalog File Format](architecture-decisions/adr002-default-catalog-file-format.md)
+  - [ADR003 - Avoid Default Exports and Prefer Named Exports](architecture-decisions/adr003-avoid-default-exports.md)
+  - [ADR004 - Module Export Structure](architecture-decisions/adr004-module-export-structure.md)
+  - [ADR005 - Catalog Core Entities](architecture-decisions/adr005-catalog-core-entities.md)
+  - [ADR006 - Avoid React.FC and React.SFC](architecture-decisions/adr006-avoid-react-fc.md)
+  - [ADR007 - Use MSW for Mocking Network Requests](architecture-decisions/adr007-use-msw-to-mock-service-requests.md)
+  - [ADR008 - Default Catalog File Name](architecture-decisions/adr008-default-catalog-file-name.md)
+- [Contribute](../CONTRIBUTING.md)
+- [Support](overview/support.md)
+- [FAQ](FAQ.md)
@@ -0,0 +1,6 @@
+---
+id: backend
+title: Backend
+---
+
+## TODO
@@ -1,4 +1,7 @@
-# Utility APIs
+---
+id: utility-apis
+title: Utility APIs
+---

 ## Introduction

@@ -153,7 +156,7 @@ The figure below shows the relationship between
 <span style="color: #b85450">fooApiRef</span>.

 <div style="text-align:center">
-<img src="utility-apis-fig1.svg" alt="Figure showing the relationship between utility APIs, the apps that provide them, and the plugins that consume them">
+<img src="../assets/utility-apis-fig1.svg" alt="Figure showing the relationship between utility APIs, the apps that provide them, and the plugins that consume them">
 </div>

 The current method for connecting Utility API providers and consumers is via the
@@ -1,4 +1,8 @@
-# ADR001: Architecture Decision Record (ADR) log
+---
+id: adrs-adr001
+title: ADR001: Architecture Decision Record (ADR) log
+sidebar_label: ADR001
+---

 | Created    | Status |
 | ---------- | ------ |
@@ -1,4 +1,8 @@
-# ADR002: Default Software Catalog File Format
+---
+id: adrs-adr002
+title: ADR002: Default Software Catalog File Format
+sidebar_label: ADR002
+---

 | Created    | Status |
 | ---------- | ------ |
@@ -1,4 +1,8 @@
-# ADR003: Avoid Default Exports and Prefer Named Exports
+---
+id: adrs-adr003
+title: ADR003: Avoid Default Exports and Prefer Named Exports
+sidebar_label: ADR003
+---

 | Created    | Status |
 | ---------- | ------ |
@@ -1,4 +1,8 @@
-# ADR004: Module Export Structure
+---
+id: adrs-adr004
+title: ADR004: Module Export Structure
+sidebar_label: ADR004
+---

 | Created    | Status |
 | ---------- | ------ |
@@ -1,4 +1,8 @@
-# ADR005: Catalog Core Entities
+---
+id: adrs-adr005
+title: ADR005: Catalog Core Entities
+sidebar_label: ADR005
+---

 | Created    | Status |
 | ---------- | ------ |
@@ -18,7 +22,7 @@ Backstage should eventually support the following core entities:
 - **Resources** are physical or virtual infrastructure needed to operate a
  component

-![Catalog Core Entities](catalog-core-entities.png)
+![Catalog Core Entities](../assets/architecture-decisions/catalog-core-entities.png)

 For now, we'll start by only implementing support for the Component entity in
 the Backstage catalog. This can later be extended to APIs, Resources and other
@@ -1,4 +1,8 @@
-# ADR006: Avoid React.FC and React.SFC
+---
+id: adrs-adr006
+title: ADR006: Avoid React.FC and React.SFC
+sidebar_label: ADR006
+---

 ## Context

@@ -1,4 +1,8 @@
-# ADR007: Use MSW to mock http requests
+---
+id: adrs-adr007
+title: ADR007: Use MSW to mock http requests
+sidebar_label: ADR007
+---

 ## Context

@@ -1,4 +1,8 @@
-# ADR008: Default Catalog File Name
+---
+id: adrs-adr008
+title: ADR008: Default Catalog File Name
+sidebar_label: ADR008
+---

 ## Background

@@ -1,4 +1,10 @@
-# Architecture Decision Records (ADR)
+---
+id: adrs-overview
+title: Architecture Decision Records (ADR)
+sidebar_label: Overview
+---
+
+#

 The substantial architecture decisions made in the Backstage project lives here.
 For more information about ADRs, when to write them, and why, please see
@@ -1,4 +1,7 @@
-# Adding authentication providers
+---
+id: add-auth-provider
+title: Adding authentication providers
+---

 ## Passport

@@ -0,0 +1,122 @@
+# Authentication backend class layout and description.
+
+## How does authentication work ?
+
+The Backstage application can use various authentication `providers` for
+authentication. A provider has to implement an `AuthProviderRouterHandlers`
+interface for handling authentication. This interface consists of 4 methods.
+Each of this method is hosted at an endpoint `/auth/[provider]/method`, where
+`method` performs a certain operation as follows:
+
+```
+  /auth/[provider]/start -> start
+  /auth/[provider]/handler/frame -> frameHandler
+  /auth/[provider]/refresh -> refresh
+  /auth/[provider]/logout -> logout
+```
+
+For more information on how these methods are used and for which purpose, refer
+to the documentation [here](oauth.md)
+
+For details on the parameters, input and output conditions for each method,
+refer to the type documentation under
+`backstage/plugins/auth-backend/src/providers/types.ts`
+
+There are currently 2 different classes for 2 authentication mechanisms that
+implement this interface: `OAuthProvider` for `OAuth` based Mechanism and a
+`SAMLAuthProvider` for a `SAML` based mechanism
+
+### `OAuth` mechanisms
+
+Currently `OAuth` is assumed to be the defacto authentication mechanism for
+backstage based applications.
+
+Backstage comes with `batteries-included` set of OAuth Providers for some
+commonly used Providers : `Okta`, `Github`, `Google` , `Gitlab` and a generic
+`oauth2` provider.
+
+All of these use the `authorization` flow of OAuth2 to implement authentication.
+
+If your `authentication` provider is any of the above mentioned (except
+`oauth2`) providers, you can configure them by setting the right variables in
+`app-config.yaml` under then `auth` section.
+
+### Configuration
+
+Each authentication (except SAML )provider needs 5 parameters: an `oauth`
+client_id, client_secret, an authorization endpoint and a token endpoint, and an
+app origin. The `appOrigin` value is the URL at which the frontend of the
+application is hosted. This is required because, the application opens a popup
+window to perform the authentication and once the flow is completed, the popup
+window sends a `postMessage` to the frontend application to indicate the result
+of the operation. Also this URL is used to verify that authentication requests
+are coming from only this endpoint.
+
+These values are configured via the `app-config.yaml` present in the root of
+your app folder
+
+```
+auth:
+  providers:
+    google:
+      development:
+        appOrigin: "http://localhost:3000/"
+        secure: false
+        clientId:
+          $secret:
+            env: AUTH_GOOGLE_CLIENT_ID
+        clientSecret:
+          $secret:
+            env: AUTH_GOOGLE_CLIENT_SECRET
+    github:
+      development:
+        appOrigin: "http://localhost:3000/"
+        secure: false
+        clientId:
+          $secret:
+            env: AUTH_GITHUB_CLIENT_ID
+        clientSecret:
+          $secret:
+            env: AUTH_GITHUB_CLIENT_SECRET
+        enterpriseInstanceUrl:
+          $secret:
+            env: AUTH_GITHUB_ENTERPRISE_INSTANCE_URL
+    gitlab:
+      development:
+        appOrigin: "http://localhost:3000/"
+        secure: false
+        clientId:
+          $secret:
+```
+
+## Technical notes
+
+### EnvironmentHandler
+
+The concept of an `env` is core to the way the `auth-backend` works. `Spotify`
+uses an `env` query parameter to identify the environment in which the
+application is running (`dev`, `staging`, `prod`, etc). Each runtime can support
+multiple environments at the same time and the right handler for each request is
+identified and dispatched to based on the `env` parameter. All
+`AuthProviderRouterHandlers` are wrapped within a `EnvironmentHandler`.
+
+An `EnvironmentHandler` takes an `id` for each provider that it wraps, the
+handlers for each of the `env` the provider is supported in, and a `function`
+that given a `Request` as argument, can extract the information about the `env`
+under which it should be processed.
+
+Each provider exposes a factory function `createXProvider` (where X = name of
+the Provider) that takes the globalconfig, env and other parameters and returns
+a `AuthProviderRouteHandler` for each env, AND, a `envIdentifier` fn to identify
+the `env` in a request.
+
+For a list of currently available providers, look in the `factories` module
+located in `backstage/plugins/auth-backend/src/providers/factories.ts`
+
+### `oauth2` provider
+
+The `oauth2` provider abstracts a generic **OAuth2+OIDC** based authentication
+provider. What this means is that after the application has been given
+permission by the user, the`authorization code` will be exchanged for an
+`access_token` , a `refresh_token` and an `id_token`. This `id_token` is used to
+obtain an email id of the user, which is then used for creating the session.
@@ -0,0 +1,6 @@
+---
+id: auth-backend
+title: Auth backend
+---
+
+## TODO
@@ -1,4 +1,7 @@
-# Glossary
+---
+id: glossary
+title: Glossary
+---

 - **Popup** - A separate browser window opened on top of the previous one.
 - **OAuth** - More specifically OAuth 2.0, a standard protocol for
@@ -1,4 +1,7 @@
-# User Authentication and Authorization in Backstage
+---
+id: index
+title: User Authentication and Authorization in Backstage
+---

 ## Summary

@@ -1,4 +1,7 @@
-# OAuth and OpenID Connect
+---
+id: oauth
+title: OAuth and OpenID Connect
+---

 This section describes how Backstage allows plugins to request OAuth Access
 Tokens and OpenID Connect ID Tokens on behalf of the user, to be used for auth
@@ -1,4 +1,7 @@
-# Defining Configuration for your Plugin
+---
+id: defining
+title: Defining Configuration for your Plugin
+---

 There is currently no tooling support or helpers for defining plugin
 configuration. But it's on the roadmap.
@@ -1,4 +1,7 @@
-# Static Configuration in Backstage
+---
+id: index
+title: Static Configuration in Backstage
+---

 ## Summary

@@ -1,4 +1,7 @@
-# Reading Backstage Configuration
+---
+id: reading
+title: Reading Backstage Configuration
+---

 ## Config API

@@ -98,7 +101,7 @@ A good pattern for reading optional configuration values is to use the `??`
 operator. For example:

 ```ts
-const title = config.getString('my-plugin.title') ?? 'My Plugin';
+const title = config.getOptionalString('my-plugin.title') ?? 'My Plugin';
 ```

 To read required configuration, simply use the methods without `Optional`, for
@@ -1,4 +1,7 @@
-# Writing Backstage Configuration Files
+---
+id: writing
+title: Writing Backstage Configuration Files
+---

 ## File Format

@@ -1,4 +1,10 @@
-# Contributing to Storybook
+---
+id: contributing-to-storybook
+title: Contributing to Storybook
+---
+
+You find our storybook at
+[http://backstage.io/storybook](http://backstage.io/storybook)

 ## Creating a new Story

@@ -26,7 +32,7 @@ core
 Go to `packages/storybook`, run `yarn install` and install the dependencies,
 then run the following on your command line: `yarn start`

-![](running-storybook.png)
+![](../assets/dls/running-storybook.png)

 _You should see a log like the image above._

@@ -34,4 +40,4 @@ If everything worked out, your server will be running on **port 6006**, go to
 your browser and navigate to `http://localhost:6006/`. You should be able to
 navigate and see the Storybook page.

-![](storybook-page.png)
+![](../assets/dls/storybook-page.png)
@@ -1,4 +1,9 @@
-![header](designheader.png)
+---
+id: design
+title: Design
+---
+
+![header](../assets/dls/designheader.png)

 Much like Backstage Open Source, this is a _living_ document! We'll keep this
 updated as we evolve our practices!
@@ -60,7 +65,7 @@ that is shaped by user experience and user interface decisions made by our
 Backstage Design Team. Also note, we encourage you to take the core experience
 we’ve crafted and add custom theming to better represent your organization!

-![dls](DLS.png)
+![dls](../assets/dls/DLS.png)

 ## ✅ Our Priorities

@@ -106,16 +111,17 @@ picked up by our team as something to be added to our design system.

 ## ✏️ Resources

-**[Storybook](http://storybook.backstage.io/)** - where you can view our
+**[Storybook](http://backstage.io/storybook)** - where you can view our
 components. If you’d like to help build up our design system, you can also add
 components we’ve designed to the Storybook as well.

-**[Figma](https://www.figma.com/@backstage)** - we're stoked to be using Figma Community to share our design assets. You can duplicate our component library and design your own plugin for Backstage.
+**[Figma](https://www.figma.com/@backstage)** - we're stoked to be using Figma
+Community to share our design assets. You can duplicate our component library
+and design your own plugin for Backstage.

 **[Discord](https://discord.gg/EBHEGzX)** - all design questions should be
 directed to the _#design_ channel.

-
 ## 🔮 Future

 ### Contributions from designers
@@ -1 +1,7 @@
-We have a [Figma component library](https://www.figma.com/@backstage) that you can use to build your own plugins for Backstage.
+---
+id: figma
+title: Figma
+---
+
+We have a [Figma component library](https://www.figma.com/@backstage) that you
+can use to build your own plugins for Backstage.
@@ -0,0 +1,6 @@
+---
+id: software-catalog-api
+title: API
+---
+
+## TODO
@@ -1,4 +1,8 @@
-# Descriptor Format of Catalog Entities
+---
+id: descriptor-format
+title: Descriptor Format of Catalog Entities
+sidebar_label: YAML File Format
+---

 This section describes the default data shape and semantics of catalog entities.

@@ -14,6 +18,8 @@ humans. However, the structure and semantics is the same in both cases.
 - [Common to All Kinds: The Envelope](#common-to-all-kinds-the-envelope)
 - [Common to All Kinds: The Metadata](#common-to-all-kinds-the-metadata)
 - [Kind: Component](#kind-component)
+- [Kind: Template](#kind-template)
+- [Kind: API](#kind-api)

 ## Overall Shape Of An Entity

@@ -80,7 +86,7 @@ The root envelope object has the following structure.
 ### `apiVersion` and `kind` [required]

 The `kind` is the high level entity type being described.
-[ADR005](/docs/architecture-decisions/adr005-catalog-core-entities.md) describes
+[ADR005](../../architecture-decisions/adr005-catalog-core-entities.md) describes
 a number of core kinds that plugins can know of and understand, but an
 organization using Backstage is free to also add entities of other kinds to the
 catalog.
@@ -252,6 +258,8 @@ spec:
  type: website
  lifecycle: production
  owner: artist-relations@example.com
+  implementsApis:
+    - artist-api
 ```

 In addition to the [common envelope metadata](#common-to-all-kinds-the-metadata)
@@ -312,14 +320,22 @@ Apart from being a string, the software catalog leaves the format of this field
 open to implementers to choose. Most commonly, it is set to the ID or email of a
 group of people in an organizational structure.

+### `spec.implementsApis` [optional]
+
+Links APIs that are implemented by the component, e.g. `artist-api`. This field
+is optional.
+
+The software catalog expects a list of one or more strings that references the
+names of other entities of the `kind` `API`.
+
 ## Kind: Template

 Describes the following entity kind:

-| Field                | Value                   |
-| -------------------- | ----------------------- |
-| `apiVersion`         | `backstage.io/v1alpha1` |
-| `Kind: Templatekind` | `Template`              |
+| Field        | Value                   |
+| ------------ | ----------------------- |
+| `apiVersion` | `backstage.io/v1alpha1` |
+| `kind`       | `Template`              |

 A Template describes a skeleton for use with the Scaffolder. It is used for
 describing what templating library is supported, and also for documenting the
@@ -422,3 +438,76 @@ specify relative to the `template.yaml` definition.

 This is also particularly useful when you have multiple template definitions in
 the same repository but only a single `template.yaml` registered in backstage.
+
+## Kind: API
+
+Describes the following entity kind:
+
+| Field        | Value                   |
+| ------------ | ----------------------- |
+| `apiVersion` | `backstage.io/v1alpha1` |
+| `kind`       | `API`                   |
+
+An API describes an interface that can be exposed by a component. The API can be
+defined in different formats, like [OpenAPI](https://swagger.io/specification/),
+[AsyncAPI](https://www.asyncapi.com/docs/specifications/latest/),
+[gRPC](https://developers.google.com/protocol-buffers), or other formats.
+
+Descriptor files for this kind may look as follows.
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: API
+metadata:
+  name: artist-api
+  description: Retrieve artist details
+spec:
+  type: openapi
+  definition: |
+    openapi: "3.0.0"
+    info:
+      version: 1.0.0
+      title: Artist API
+      license:
+        name: MIT
+    servers:
+      - url: http://artist.spotify.net/v1
+    paths:
+      /artists:
+        get:
+          summary: List all artists
+    ...
+```
+
+In addition to the [common envelope metadata](#common-to-all-kinds-the-metadata)
+shape, this kind has the following structure.
+
+### `apiVersion` and `kind` [required]
+
+Exactly equal to `backstage.io/v1alpha1` and `API`, respectively.
+
+### `spec.type` [required]
+
+The type of the API definition as a string, e.g. `openapi`. This field is
+required.
+
+The software catalog accepts any type value, but an organisation should take
+great care to establish a proper taxonomy for these. Tools including Backstage
+itself may read this field and behave differently depending on its value. For
+example, an OpenAPI type API may be displayed using an OpenAPI viewer tooling in
+the Backstage interface.
+
+The current set of well-known and common values for this field is:
+
+- `openapi` - An API definition in YAML or JSON format based on the
+  [OpenAPI](https://swagger.io/specification/) version 2 or version 3 spec.
+- `asyncapi` - An API definition based on the
+  [AsyncAPI](https://www.asyncapi.com/docs/specifications/latest/) spec.
+- `grpc` - An API definition based on
+  [Protocol Buffers](https://developers.google.com/protocol-buffers) to use with
+  [gRPC](https://grpc.io/).
+
+### `spec.definition` [required]
+
+The definition of the API, based on the format defined by `spec.type`. This
+field is required.
@@ -0,0 +1,41 @@
+---
+id: extending-the-model
+title: Extending the model
+---
+
+Backstage natively supports tracking of the following component
+[`type`](descriptor-format.md)'s:
+
+- Services
+- Websites
+- Libraries
+- Documentation
+- Other
+
+![](bsc-extend.png)
+
+Since these types are likely not the only kind of software you will want to
+track in Backstage, it is possible to
+
+It is possible to add your own software types that fits your organization's data
+model. Inside Spotify our model has grown significantly over the years, and now
+includes ML models, Apps, data pipelines and many more.
+
+## Adding a new type
+
+TODO: Describe what changes are needed to add a new type that shows up in the
+catalog.
+
+## The Other type
+
+It might be tempting to put software that doesn't fit into any of the existing
+types into Other. There are a few reasons why we advice against this; firstly,
+we have found that it is preferred to match the conceptual model that your
+engineers have when describing your sofware. Secondly, Backstage helps your
+engineers manage their software by integrating the infratrucure tooling through
+plugins. Different plugins are used for managing different types of components.
+
+For example, the
+[Lighthouse plugin](https://github.com/spotify/backstage/tree/master/plugins/lighthouse)
+only makes sense for Websites. The more specific you can be in how you model
+your software, the easier it is to provide plugins that are contextual.
@@ -0,0 +1,11 @@
+---
+id: external-integrations
+title: External integrations
+---
+
+Backstage natively supports storing software components in
+[metadata YAML files](descriptor-format.md). However, companies that already
+have an existing system for keeping track of software and its owners can
+integrate such systems with Backstage.
+
+TODO: Describe the API contract.
@@ -1,4 +1,7 @@
-# Backstage Service Catalog (alpha)
+---
+id: software-catalog-overview
+title: Backstage Service Catalog (alpha)
+---

 ## What is a Service Catalog?

@@ -6,24 +9,115 @@ The Backstage Service Catalog — actually, a software catalog, since it include
 more than just services — is a centralized system that keeps track of ownership
 and metadata for all the software in your ecosystem (services, websites,
 libraries, data pipelines, etc). The catalog is built around the concept of
-[metadata yaml files](../../architecture-decisions/adr002-default-catalog-file-format.md#format)
-stored together with the code, which are then harvested and visualized in
-Backstage.
+[metadata YAML files](descriptor-format.md) stored together with the code, which
+are then harvested and visualized in Backstage.

 ![service-catalog](https://backstage.io/blog/assets/6/header.png)

-We have also found that the service catalog is a great way to organise the
-infrastructure tools you use to manage the software as well. This is how
-Backstage creates one developer portal for all your tools. Rather than asking
-teams to jump between different infrastructure UI’s (and incurring additional
-cognitive overhead each time they make a context switch), most of these tools
-can be organised around the entities in the catalog.
+## How it works

-## Using the Service Catalog
+Backstage and the Backstage Service Catalog makes it easy for one team to manage
+10 services — and makes it possible for your company to manage thousands of
+them.

-TODO
+More specifically, the Service Catalog enables two main use-cases:

-![](service-catalog-home.png)
+1. Helping teams manage and maintain the software they own. Teams get a uniform
+   view of all their software; services, libraries, websites, ML models — you
+   name it, Backstage knows all about it.
+2. Makes all the software in your company, and who owns it, discoverable. No
+   more orphan software hiding in the dark corners of your software ecosystem.
+
+## Getting Started
+
+The Software Catalog is available to browse on the start page at `/`. If you've
+followed [Installing in your Backstage App](./installation.md) in your separate
+App or [Getting Started with Backstage](../../getting-started) for this repo,
+you should be able to browse the catalog at `http://localhost:3000`.
+
+![](../../assets/software-catalog/service-catalog-home.png)
+
+## Adding components to the catalog
+
+The source of truth for the components in your service catalog are
+[metadata YAML files](descriptor-format.md) stored in source control (GitHub,
+GitHub Enterprise, GitLab, ...).
+
+There are 3 ways to add components to the catalog:
+
+1. Manually register components
+2. Creating new components through Backstage
+3. Integrating with and [external source](external-integrations.md)
+
+### Manually register components
+
+Users can register new components by going to `/create` and clicking the
+**REGISTER EXISTING COMPONENT** button:
+
+![](bsc-register-1.png)
+
+Backstage expects the full URL to the YAML in your source control. Example:
+
+```
+https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/artist-lookup-component.yaml
+```
+
+_More examples can be found
+[here](https://github.com/spotify/backstage/tree/master/packages/catalog-model/examples)._
+
+![](bsc-register-2.png)
+
+It is important to note that any kind of software can be registered in
+Backstage. Even if the software is not maintained by your company (SaaS
+offering, for example) it is still useful to create components for tracking
+ownership.
+
+### Creating new components through Backstage
+
+All software created through the
+[Backstage Software Templates](../software-templates/index.md) are automatically
+registered in the catalog.
+
+### Updating component metadata
+
+Teams owning the components are responsible for maintaining the metadata about
+them, and do so using their normal Git workflow.
+
+![](bsc-edit.png)
+
+Once the change has been merged, Backstage will automatically show the updated
+metadata in the service catalog after a short while.
+
+## Finding software in the catalog
+
+By default the service catalog shows components owned by the team of the logged
+in user. But you can also switch to _All_ to see all the components across your
+companie's software ecosystem. Basic inline _search_ and _column filtering_
+makes it easy to browse a big set of components.
+
+![](bsc-search.png)
+
+## Starring components
+
+For easy and quick access to components you visit frequently, Backstage supports
+_starring_ of components:
+
+![](bsc-starred.png)
+
+## Integrated tooling through plugins
+
+The service catalog is a great way to organise the infrastructure tools you use
+to manage the software. This is how Backstage creates one developer portal for
+all your tools. Rather than asking teams to jump between different
+infrastructure UI’s (and incurring additional cognitive overhead each time they
+make a context switch), most of these tools can be organised around the entities
+in the catalog.
+
+![tools](https://backstage.io/blog/assets/20-05-20/tabs.png)
+
+The Backstage platform can be customized by incorporating
+[existing open source plugins](https://github.com/spotify/backstage/tree/master/plugins),
+or by [building your own](../../plugins/index.md).

 ## Links

@@ -0,0 +1,193 @@
+# Installing in your Backstage App
+
+The catalog plugin comes in two packages, `@backstage/plugin-catalog` and
+`@backstage/plugin-catalog-backend`. Each has their own installation steps,
+outlined below.
+
+## Installing @backstage/plugin-catalog
+
+> **Note that if you used `npx @backstage/create-app`, the plugin may already be
+> present**
+
+The catalog frontend plugin should be installed in your `app` package, which is
+created as a part of `@backstage/create-app`. To install the package, run:
+
+```bash
+cd packages/app
+yarn add @backstage/plugin-catalog
+```
+
+Make sure the version of `@backstage/plugin-catalog` matches the version of
+other `@backstage` packages. You can update it in `packages/app/package.json` if
+it doesn't.
+
+### Adding the Plugin to your `packages/app`
+
+Add the following entry to the head of your `packages/app/src/plugins.ts`:
+
+```ts
+export { plugin as CatalogPlugin } from '@backstage/plugin-catalog';
+```
+
+Add the following to your `packages/app/src/apis.ts`:
+
+```ts
+import { catalogApiRef, CatalogClient } from '@backstage/plugin-catalog';
+
+// Inside the ApiRegistry builder function ...
+
+builder.add(
+  catalogApiRef,
+  new CatalogClient({
+    apiOrigin: backendUrl,
+    basePath: '/catalog',
+  }),
+);
+```
+
+Where `backendUrl` is the `backend.baseUrl` from config, i.e.
+`const backendUrl = config.getString('backend.baseUrl')`.
+
+The catalog components depend on a number of other
+[Utility APIs](../../api/utility-apis.md) to function, including at least the
+`ErrorApi` and `StorageApi`. You can find an example of how to install these in
+your app
+[here](https://github.com/spotify/backstage/blob/61c3a7e5b750dc7c059ef16b188594d31b2c04c2/packages/app/src/apis.ts#L80).
+
+## Gotchas that we will fix
+
+Since the catalog plugin currently ships with a sentry plugin `InfoCard`
+installed by default, you'll need to set `sentry.organization` in your
+`app-yaml.yaml`. For example:
+
+```yaml
+sentry:
+  organization: Acme Corporation
+```
+
+If you've created an app with an older version of `@backstage/create-app` or
+`@backstage/cli create-app`, be sure to remove the Welcome plugin from the app,
+as that will conflict with the catalog routes.
+
+## Installing @backstage/plugin-catalog-backend
+
+> **Note that if you used `npx @backstage/create-app`, the plugin may already be
+> present**
+
+The catalog backend should be installed in your `backend` package, which is
+created as a part of `@backstage/create-app`. To install the package, run:
+
+```bash
+cd packages/backend
+yarn add @backstage/plugin-catalog-backend
+```
+
+Make sure the version of `@backstage/plugin-catalog-backend` matches the version
+of other `@backstage` packages. You can update it in
+`packages/backend/package.json` if it doesn't.
+
+### Adding the Plugin to your `packages/backend`
+
+You'll need to add the plugin to the `backend`'s router. You can do this by
+creating a file called `packages/backend/src/plugins/catalog.ts` with the
+following contents to get you up and running quickly.
+
+```ts
+import {
+  createRouter,
+  DatabaseEntitiesCatalog,
+  DatabaseLocationsCatalog,
+  DatabaseManager,
+  HigherOrderOperations,
+  LocationReaders,
+  runPeriodically,
+} from '@backstage/plugin-catalog-backend';
+import { PluginEnvironment } from '../types';
+import { useHotCleanup } from '@backstage/backend-common';
+
+export default async function createPlugin({
+  logger,
+  database,
+}: PluginEnvironment) {
+  const locationReader = new LocationReaders(logger);
+
+  const db = await DatabaseManager.createDatabase(database, { logger });
+  const entitiesCatalog = new DatabaseEntitiesCatalog(db);
+  const locationsCatalog = new DatabaseLocationsCatalog(db);
+  const higherOrderOperation = new HigherOrderOperations(
+    entitiesCatalog,
+    locationsCatalog,
+    locationReader,
+    logger,
+  );
+
+  useHotCleanup(
+    module,
+    runPeriodically(() => higherOrderOperation.refreshAllLocations(), 10000),
+  );
+
+  return await createRouter({
+    entitiesCatalog,
+    locationsCatalog,
+    higherOrderOperation,
+    logger,
+  });
+}
+```
+
+Once the `catalog.ts` router setup file is in place, add the router to
+`packages/backend/src/index.ts`:
+
+```ts
+import catalog from './plugins/catalog';
+
+const catalogEnv = useHotMemoize(module, () => createEnv('catalog'));
+
+const service = createServiceBuilder(module)
+  .loadConfig(configReader)
+  /** several different routers */
+  .addRouter('/catalog', await catalog(catalogEnv));
+```
+
+### Adding Entries to the Catalog
+
+At this point the catalog backend is installed in your backend package, but you
+will not have any entities loaded.
+
+To get up and running and try out some templates quickly, you can add some of
+our example templates through static configuration. Add the following to the
+`catalog.locations` section in your `app-config.yaml`:
+
+```yaml
+catalog:
+  locations:
+    # Backstage Example Component
+    - type: github
+      target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/artist-lookup-component.yaml
+    - type: github
+      target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/playback-order-component.yaml
+    - type: github
+      target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/podcast-api-component.yaml
+    - type: github
+      target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/queue-proxy-component.yaml
+    - type: github
+      target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/searcher-component.yaml
+    - type: github
+      target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/playback-lib-component.yaml
+    - type: github
+      target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/www-artist-component.yaml
+    - type: github
+      target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/shuffle-api-component.yaml
+```
+
+### Running the Backend
+
+Finally, start up the backend with the new configuration:
+
+```bash
+cd packages/backend
+yarn start
+```
+
+If you've also set up the frontend plugin, so you should be ready to go browse
+the catalog at [localhost:3000](http://localhost:3000) now!
@@ -0,0 +1,99 @@
+---
+id: system-model
+title: System Model
+---
+
+We believe that a strong shared understanding and terminology around systems,
+software and resources leads to a better Backstage experience.
+
+_This description originates from
+[this RFC](https://github.com/spotify/backstage/issues/390). Note that some of
+the concepts are not yet supported in Backstage._
+
+## Concepts
+
+We model our technology using these five concepts (further explained below):
+
+- **Domains** are a high-level grouping of systems
+- **Systems** encapsulate the implementation of APIs
+- **APIs** are the boundaries between different components and systems
+- **Components** are pieces of software
+- **Resources** are physical or virtual infrastructure needed to operate a
+  system
+
+![Software Ecosystem Model_ Public Github version](https://user-images.githubusercontent.com/24575/77633084-39bcde80-6f4f-11ea-8251-f8df561a3652.png)
+
+### Domain
+
+While systems are the basic level of encapsulation for resources, components and
+APIs, it is often useful to group a collection of systems that share
+terminology, domain models, business purpose, or documentation, i.e. they form a
+bounded context.
+
+For example, it would make sense if the different systems in the “Payments”
+domain would come with some documentation on how to accept payments for a new
+product or use-case, share the same entity types in their APIs, and integrate
+well with each other.
+
+### System
+
+With increasing complexity in software, we believe that systems form an
+important abstraction level to help us reason about software ecosystems. Systems
+are a useful concept in that they allow us to ignore the implementation details
+of a certain functionality for consumers, while allowing the owning team to make
+changes as they see fit (leading to low coupling).
+
+A system, in this sense, is a collection of resources and components that
+exposes one or several APIs. Components and resources in a system are typically
+owned by the same team and are expected to co-evolve. As such, systems usually
+consist of at most a handful of components.
+
+For example, a playlist management system might encapsulate a backend service to
+update playlists, a backend service to query them, and a database to store them.
+It could expose an RPC API, a daily snapshots dataset, and an event stream of
+playlist updates.
+
+### Component
+
+A component is a piece of software, for example a mobile feature, web site,
+backend service or data pipeline (list not exhaustive). A component can be
+tracked in source control, or use some existing open source or commercial
+software.
+
+A component can implement APIs for other components to consume. It might depend
+on the resources of the system it belongs to, and APIs from other components or
+other systems. All other aspects of the component, e.g. any code dependencies,
+must be encapsulated.
+
+### API
+
+We believe APIs form an important (maybe the most important) abstraction that
+allows large software ecosystems to scale. Thus, APIs are a first class citizen
+in the Backstage model and the primary way to discover existing functionality in
+the ecosystem.
+
+APIs are implemented by components and form boundaries between components and
+systems. They might be defined using an RPC IDL (eg Protobuf, GraphQL, ...), a
+data schema (eg Avro, TFRecord, ...), or as code interfaces. In any case, APIs
+exposed by components need to be in a known machine-readable format so we can
+build further tooling and analysis on top.
+
+Some APIs might be exposed by the system, making them available for any other
+Spotify component to consume. Those public APIs must be documented and humanly
+discoverable in Backstage.
+
+### Resource
+
+Resources are the infrastructure a system needs to operate, like BigTable
+databases, Pub/Sub topics, S3 buckets or CDNs. Modelling them together with
+components and systems will better allow us to visualize resource footprint, and
+create tooling around them.
+
+## Current status
+
+Backstage currently supports Components and APIs.
+
+## Links
+
+- [Original RFC](https://github.com/spotify/backstage/issues/390)
+- [YAML file format](../../architecture-decisions/adr002-default-catalog-file-format.md)
@@ -1,4 +1,7 @@
-# Adding your own Templates
+---
+id: adding-templates
+title: Adding your own Templates
+---

 Templates are stored in the **Service Catalog** under a kind `Template`. The
 minimum that the a template skeleton needs is a `template.yaml` but it would be
@@ -15,7 +18,8 @@ metadata:
  # title of the template
  title: React SSR Template
  # a description of the template
-  description: Next.js application skeleton for creating isomorphic web applications.
+  description:
+    Next.js application skeleton for creating isomorphic web applications.
  # some tags to display in the frontend
  tags:
    - Recommended
@@ -39,7 +43,7 @@ spec:
        type: string
        description: Unique name of the component
      description:
-        title:  Description
+        title: Description
        type: string
        description: Description of the component
 ```
@@ -1,4 +1,7 @@
-# Create your own Preparer
+---
+id: extending-preparer
+title: Create your own Preparer
+---

 Preparers are responsible for reading the location of the definition of a
 [Template Entity](../../software-catalog/descriptor-format.md#kind-template) and
@@ -1,4 +1,7 @@
-# Create your own Publisher
+---
+id: extending-publisher
+title: Create your own Publisher
+---

 Publishers are responsible for pushing and storing the templated skeleton after
 the values have been templated by the `Templater`. See
@@ -1,4 +1,7 @@
-# Creating your own Templater
+---
+id: extending-templater
+title: Creating your own Templater
+---

 Templaters are responsible for taking the directory path for the skeleton
 returned by the preparers, and then executing the templating command on top of
@@ -1,4 +1,7 @@
-## Extending the Scaffolder
+---
+id: extending-index
+title: Extending the Scaffolder
+---

 Welcome. Take a seat. You're at the Scaffolder Documentation.

@@ -1,19 +1,27 @@
-# Software Templates
+---
+id: software-templates-index
+title: Software Templates
+---

 The Software Templates part of Backstage is a tool that can help you create
 Components inside Backstage. It by default has the ability to load skeletons of
 code, template in some variables and then publish the template to some location
 like GitHub.

+<video width="100%" height="100%" controls>
+  <source src="https://backstage.io/blog/assets/2020-08-05/feature.mp4" type="video/mp4">
+</video>
+
 ### Getting Started

-The Software Templates are available under `/create`, and if you've followed
-[Getting Started with Backstage](../../getting-started), you should be able to
-reach `http://localhost:3000/create`.
+The Software Templates are available under `/create`. If you've followed
+[Installing in your Backstage App](./installation.md) in your separate App or
+[Getting Started with Backstage](../../getting-started) for this repo, you
+should be able to reach `http://localhost:3000/create`.

 You should get something that looks similar to this:

-![Create Image](./assets/create.png)
+![Create Image](../../assets/software-templates/create.png)

 ### Choose a template

@@ -22,38 +30,38 @@ page which may or may not look different for each template. Each template can
 ask for different input variables, and they are then passed to the templater
 internally.

-![Enter some variables](./assets/template-picked.png)
+![Enter some variables](../../assets/software-templates/template-picked.png)

 After filling in these variables, you'll get some more fields to fill out which
 are required for backstage usage. The owner, which is a `user` in the backstage
 system, and the `storePath` which right now must be a Github Organisation and a
-non-existing github repository name in the format `organistaion/reponame`.
+non-existing github repository name in the format `organisation/reponame`.

-![Enter backstage vars](./assets/template-picked-2.png)
+![Enter backstage vars](../../assets/software-templates/template-picked-2.png)

 ### Run!

 Once you've entered values and confirmed, you'll then get a modal with live
 progress of what is currently happening with the creation of your template.

-![Templating Running](./assets/running.png)
+![Templating Running](../../assets/software-templates/running.png)

 It shouldn't take too long, and you'll have a success screen!

-![Templating Complete](./assets/complete.png)
+![Templating Complete](../../assets/software-templates/complete.png)

 If it fails, you'll be able to click on each section to get the log from the
 step that failed which can be helpful to debug.

-![Templating failed](./assets/failed.png)
+![Templating failed](../../assets/software-templates/failed.png)

 ### View Component in Catalog

 When it's been created you'll see the `View in Catalog` button, which will take
 you to the registered component in the catalog:

-![Catalog](./assets/go-to-catalog.png)
+![Catalog](../../assets/software-templates/go-to-catalog.png)

 And then you'll also be able to see it in the Catalog View table

-![Catalog](./assets/added-to-the-catalog-list.png)
+![Catalog](../../assets/software-templates/added-to-the-catalog-list.png)
@@ -0,0 +1,194 @@
+# Installing in your Backstage App
+
+The scaffolder plugin comes in two packages, `@backstage/plugin-scaffolder` and
+`@backstage/plugin-scaffolder-backend`. Each has their own installation steps,
+outlined below.
+
+The Scaffolder plugin also depends on the Software Catalog. Instructions for how
+to set that up can be found [here](../software-catalog/installation.md).
+
+## Installing @backstage/plugin-scaffolder
+
+> **Note that if you used `npx @backstage/create-app`, the plugin may already be
+> present**
+
+The scaffolder frontend plugin should be installed in your `app` package, which
+is created as a part of `@backstage/create-app`. To install the package, run:
+
+```bash
+cd packages/app
+yarn add @backstage/plugin-scaffolder
+```
+
+Make sure the version of `@backstage/plugin-scaffolder` matches the version of
+other `@backstage` packages. You can update it in `packages/app/package.json` if
+it doesn't.
+
+### Adding the Plugin to your `packages/app`
+
+Add the following entry to the head of your `packages/app/src/plugins.ts`:
+
+```ts
+export { plugin as ScaffolderPlugin } from '@backstage/plugin-scaffolder';
+```
+
+Add the following to your `packages/app/src/apis.ts`:
+
+```ts
+import { scaffolderApiRef, ScaffolderApi } from '@backstage/plugin-scaffolder';
+
+// Inside the ApiRegistry builder function ...
+
+builder.add(
+  scaffolderApiRef,
+  new ScaffolderApi({
+    apiOrigin: backendUrl,
+    basePath: '/scaffolder/v1',
+  }),
+);
+```
+
+Where `backendUrl` is the `backend.baseUrl` from config, i.e.
+`const backendUrl = config.getString('backend.baseUrl')`.
+
+This is all that is needed for the frontend part of the Scaffolder plugin to
+work!
+
+## Installing @backstage/plugin-scaffolder-backend
+
+> **Note that if you used `npx @backstage/create-app`, the plugin may already be
+> present**
+
+The scaffolder backend should be installed in your `backend` package, which is
+created as a part of `@backstage/create-app`. To install the package, run:
+
+```bash
+cd packages/backend
+yarn add @backstage/plugin-scaffolder-backend
+```
+
+Make sure the version of `@backstage/plugin-scaffolder-backend` matches the
+version of other `@backstage` packages. You can update it in
+`packages/backend/package.json` if it doesn't.
+
+### Adding the Plugin to your `packages/backend`
+
+You'll need to add the plugin to the `backend`'s router. You can do this by
+creating a file called `packages/backend/src/plugins/scaffolder.ts` with the
+following contents to get you up and running quickly.
+
+```ts
+import {
+  CookieCutter,
+  createRouter,
+  FilePreparer,
+  GithubPreparer,
+  Preparers,
+  GithubPublisher,
+  CreateReactAppTemplater,
+  Templaters,
+} from '@backstage/plugin-scaffolder-backend';
+import { Octokit } from '@octokit/rest';
+import type { PluginEnvironment } from '../types';
+import Docker from 'dockerode';
+
+export default async function createPlugin({ logger }: PluginEnvironment) {
+  const cookiecutterTemplater = new CookieCutter();
+  const craTemplater = new CreateReactAppTemplater();
+  const templaters = new Templaters();
+
+  // Register default templaters
+  templaters.register('cookiecutter', cookiecutterTemplater);
+  templaters.register('cra', craTemplater);
+
+  const filePreparer = new FilePreparer();
+  const githubPreparer = new GithubPreparer();
+  const preparers = new Preparers();
+
+  // Register default preparers
+  preparers.register('file', filePreparer);
+  preparers.register('github', githubPreparer);
+
+  // Create Github client with your access token from environment variables
+  const githubClient = new Octokit({ auth: process.env.GITHUB_ACCESS_TOKEN });
+  const publisher = new GithubPublisher({ client: githubClient });
+
+  const dockerClient = new Docker();
+  return await createRouter({
+    preparers,
+    templaters,
+    publisher,
+    logger,
+    dockerClient,
+  });
+}
+```
+
+Once the `scaffolder.ts` router setup file is in place, add the router to
+`packages/backend/src/index.ts`:
+
+```ts
+import scaffolder from './plugins/scaffolder';
+
+const scaffolderEnv = useHotMemoize(module, () => createEnv('scaffolder'));
+
+const service = createServiceBuilder(module)
+  .loadConfig(configReader)
+  /** several different routers */
+  .addRouter('/scaffolder', await scaffolder(scaffolderEnv));
+```
+
+### Adding Templates
+
+At this point the scaffolder backend is installed in your backend package, but
+you will not have any templates available to use. These need to be added to the
+software catalog, as they are represented as entities of kind
+[Template](../software-catalog/descriptor-format.md#kind-template). You can find
+out more about adding templates [here](./adding-templates.md).
+
+To get up and running and try out some templates quickly, you can add some of
+our example templates through static configuration. Add the following to the
+`catalog.locations` section in your `app-config.yaml`:
+
+```yaml
+catalog:
+  locations:
+    # Backstage Example Templates
+    - type: github
+      target: https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/sample-templates/react-ssr-template/template.yaml
+    - type: github
+      target: https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/sample-templates/springboot-grpc-template/template.yaml
+    - type: github
+      target: https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/sample-templates/create-react-app/template.yaml
+    - type: github
+      target: https://github.com/spotify/cookiecutter-golang/blob/master/template.yaml
+```
+
+### Runtime Dependencies
+
+For the scaffolder backend plugin to function, it needs a GitHub access token,
+and access to a running Docker daemon. You can create a GitHub access token
+[here](https://github.com/settings/tokens/new), select `repo` scope only. Full
+docs on creating private GitHub access tokens is available
+[here](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token).
+Note that the need for private GitHub access tokens will be replaced with GitHub
+Apps integration further down the line.
+
+> **Right now it is only possible to scaffold repositories inside GitHub
+> organizations, and not under personal accounts.**
+
+The GitHub access token is passed along using the `GITHUB_ACCESS_TOKEN`
+environment variable.
+
+### Running the Backend
+
+Finally, make sure you have a local Docker daemon running, and start up the
+backend with the new configuration:
+
+```bash
+cd packages/backend
+GITHUB_ACCESS_TOKEN=<token> yarn start
+```
+
+If you've also set up the frontend plugin, so you should be ready to go browse
+the templates at [localhost:3000/create](http://localhost:3000/create) now!
@@ -1,8 +1,13 @@
-# TechDocs FAQ
+---
+id: faqs
+title: TechDocs FAQ
+sidebar_label: FAQ
+---

 This page answers frequently asked questions about [TechDocs](README.md).

-_Got a question that you think others might be interested in knowing the answer to? Edit this file
+_Got a question that you think others might be interested in knowing the answer
+to? Edit this file
 [here](https://github.com/spotify/backstage/edit/master/docs/features/techdocs/FAQ.md)._

 ## Technology
@@ -25,4 +30,3 @@ package is a MkDocs Plugin that works like a wrapper around multiple MkDocs
 plugins (e.g.
 [MkDocs Monorepo Plugin](https://github.com/spotify/mkdocs-monorepo-plugin)) as
 well as a selection of Python Markdown extensions that TechDocs supports.
-
@@ -1,4 +1,8 @@
-# TechDocs Documentation
+---
+id: techdocs-overview
+title: TechDocs Documentation
+sidebar_label: Overview
+---

 ## What is it?

@@ -16,9 +20,9 @@ Spotify’s developer experience offering with 2,400+ documentation sites and
 - A clear end-to-end docs-like-code solution. (_Coming soon in V.1_)

 - A tightly coupled feedback loop with the developer workflow. (_Coming soon in
-  V.2_)
+  V.3_)

- A developer ecosystem for creating extensions. (_Coming soon in V.2_)
+- A developer ecosystem for creating extensions. (_Coming soon in V.3_)

 ## Project roadmap

@@ -1,6 +1,10 @@
-# Concepts
+---
+id: concepts
+title: Concepts
+---

-This page describes concepts that are introduced with Spotify's docs-like-code solution in Backstage.
+This page describes concepts that are introduced with Spotify's docs-like-code
+solution in Backstage.

 ### TechDocs Core Plugin

@@ -8,7 +12,7 @@ The TechDocs Core Plugin is a MkDocs plugin created as a wrapper around multiple
 MkDocs plugins and Python Markdown extensions to standardize the configuration
 of MkDocs used for TechDocs.

-[TechDocs Core](../../../packages/techdocs-container/techdocs-core/README.md)
+[TechDocs Core](https://github.com/spotify/backstage/blob/master/packages/techdocs-container/techdocs-core/README.md)

 ### TechDocs container

@@ -17,7 +21,7 @@ The TechDocs container is a Docker container available at
 pages, including stylesheets and scripts from Python flavored Markdown, through
 MkDocs.

-[TechDocs Container](../../../packages/techdocs-container/README.md)
+[TechDocs Container](https://github.com/spotify/backstage/blob/master/packages/techdocs-container/README.md)

 ### TechDocs publisher (coming soon)

@@ -28,7 +32,7 @@ documentation for publishing. Currently it mostly acts as a wrapper around the
 TechDocs container and provides an easy-to-use interface for our docker
 container.

-[TechDocs CLI](../../../packages/techdocs-cli/README.md)
+[TechDocs CLI](https://github.com/spotify/backstage/blob/master/packages/techdocs-cli/README.md)

 ### TechDocs Reader

@@ -40,7 +44,7 @@ The TechDocs Reader purpose is also to open up the opportunity to integrate
 TechDocs widgets for a customized full-featured TechDocs experience.
 ([coming soon V.2](https://github.com/spotify/backstage/milestone/17))

-[TechDocs Reader](../../../plugins/techdocs/src/reader/README.md)
+[TechDocs Reader](https://github.com/spotify/backstage/blob/master/plugins/techdocs/src/reader/README.md)

 ### Transformers

@@ -49,4 +53,4 @@ Reader. The reason why transformers were introduced was to provide a way to
 transform the HTML content on pre and post render (e.g. rewrite docs links or
 modify css).

-[Transformers API docs](../../../plugins/techdocs/src/reader/transformers/README.md)
+[Transformers API docs](https://github.com/spotify/backstage/blob/master/plugins/techdocs/src/reader/transformers/README.md)
@@ -1,22 +1,29 @@
-# Creating and publishing your docs
+---
+id: creating-and-publishing
+title: Creating and publishing your docs
+sidebar_label: Creating and Publishing Documentation
+---

 This section will guide you through:

 - Creating a basic setup for your documentation
 - Writing and previewing your documentation in a local Backstage environment
 - Creating a build ready for publication
- Publishing your documentation and making your Backstage instance read your published docs.
+- Publishing your documentation and making your Backstage instance read your
+  published docs.

 ## Prerequisities

 - [Docker](https://docs.docker.com/get-docker/)
 - Static file hosting
- A working Backstage instance with TechDocs installed
-  (see [TechDocs getting started](getting-started.md))
+- A working Backstage instance with TechDocs installed (see
+  [TechDocs getting started](getting-started.md))

 ## Create a basic documentation setup

-In your home directory (also known as `~`), create a directory that contains your documentation (for example, `hello-docs`). Inside this directory, create a file called `mkdocs.yml`. Below is a basic example of how it could look.
+In your home directory (also known as `~`), create a directory that contains
+your documentation (for example, `hello-docs`). Inside this directory, create a
+file called `mkdocs.yml`. Below is a basic example of how it could look.

 The `~/hello-docs/mkdocs.yml` file should have the following content:

@@ -65,15 +72,19 @@ You should now have a folder called `~/hello-docs/site/`.

 ## Deploy to a file server

-In order to serve documentation to TechDocs, our Backstage plugin needs to download the HTML rendered from the previous step. This will likely exist on an external file server, or a storage solution such as Google Cloud Storage.
+In order to serve documentation to TechDocs, our Backstage plugin needs to
+download the HTML rendered from the previous step. This will likely exist on an
+external file server, or a storage solution such as Google Cloud Storage.

-When deploying documentation, it should be deployed on that file server/storage solution with the following convention: `{id}/{file}`. For example, if
-you want to upload the `getting-started/index.html` file for the `backstage`
+When deploying documentation, it should be deployed on that file server/storage
+solution with the following convention: `{id}/{file}`. For example, if you want
+to upload the `getting-started/index.html` file for the `backstage`
 documentation site, we would upload it to our file server as
 `backstage/getting-started/index.html`.

 To explain further what this would look like for multiple documentation sites,
-take a look at this example file tree that would be represented on your file server:
+take a look at this example file tree that would be represented on your file
+server:

 ```md
 /backstage/index.html /backstage/getting-started/index.html
@@ -87,17 +98,19 @@ In this file tree, we have two documentation sites available: `backstage` and
 on `http://example.com` as the server URL.

 When you configure the TechDocs plugin in Backstage to use `http://example.com`
-as the file server/storage solution, it will translate the following URLs to
-the file server:
+as the file server/storage solution, it will translate the following URLs to the
+file server:

 | Backstage URL                                             | File Server URL                                         |
 | --------------------------------------------------------- | ------------------------------------------------------- |
 | https://demo.backstage.io/docs/backstage/                 | http://example.com/backstage/index.html                 |
 | https://demo.backstage.io/docs/mkdocs/plugin-development/ | http://example.com/mkdocs/plugin-development/index.html |

-Then deploying new sites is easy: simply copy over the `site/`
-folder produced in the [Create documentation](#build-production-ready-documentation) step above to the file server/storage solution under the ID of the documentation site. It will then become immediately available in Backstage under
-the same ID as you can see in the table above.
+Then deploying new sites is easy: simply copy over the `site/` folder produced
+in the [Create documentation](#build-production-ready-documentation) step above
+to the file server/storage solution under the ID of the documentation site. It
+will then become immediately available in Backstage under the same ID as you can
+see in the table above.

 So, if the URL to your file server is `http://example.com/`, your
 `~/hello-docs/site` folder containing the documentation should be accessible at
@@ -1,17 +1,20 @@
-# Getting Started
+---
+id: getting-started
+title: Getting Started
+---

 > TechDocs is not yet feature complete - currently you can't set up a complete
 > end-to-end working TechDocs plugin without customizing the plugin itself.

-> What you can expect from TechDocs V.0 is a demonstration of how to integrate docs into
-> Backstage. TechDocs can create docs using
+> What you can expect from TechDocs V.0 is a demonstration of how to integrate
+> docs into Backstage. TechDocs can create docs using
 > [mkdocs](https://www.mkdocs.org/), as well as read published docs. If you
 > publish generated docs and pass in a `storageUrl` in your `app-config.yaml`,
 > you can view them in Backstage by going to
 > `http://localhost:3000/docs/<remote-folder>`.

-TechDocs functions as a plugin to
-Backstage, so you will need to use Backstage to use TechDocs.
+TechDocs functions as a plugin to Backstage, so you will need to use Backstage
+to use TechDocs.

 ## What is Backstage?

@@ -38,17 +41,20 @@ To create a new Backstage application for TechDocs, run the following command:
 npx @backstage/cli create-app
 ```

-You will then be prompted to enter a name for your application. Once that's done, a new Backstage application will be created in a new folder. For
-example, if you choose the name `hello-world`, a new `hello-world` folder is created containing your new Backstage application.
+You will then be prompted to enter a name for your application. Once that's
+done, a new Backstage application will be created in a new folder. For example,
+if you choose the name `hello-world`, a new `hello-world` folder is created
+containing your new Backstage application.

 ## Installing TechDocs

-TechDocs is not provided with the Backstage application by default, so you will now need to set up TechDocs manually. It should take less
-than a minute.
+TechDocs is not provided with the Backstage application by default, so you will
+now need to set up TechDocs manually. It should take less than a minute.

 ### Adding the package

-The first step is to add the TechDocs plugin to your Backstage application. Navigate to your new Backstage application folder:
+The first step is to add the TechDocs plugin to your Backstage application.
+Navigate to your new Backstage application folder:

 ```bash
 cd hello-world/
@@ -61,7 +67,7 @@ cd packages/app
 yarn add @backstage/plugin-techdocs
 ```

-After a short while, the TechDocs plugin should be successfully installed. 
+After a short while, the TechDocs plugin should be successfully installed.

 Next, you need to set up some basic configuration. Enter the following command:

@@ -78,7 +84,8 @@ export { plugin as TechDocs } from '@backstage/plugin-techdocs';
 ### Setting the configuration

 TechDocs allows for configuration of the docs storage URL through your
-`app-config` file. The URL provided here is for demo docs to use for testing purposes.
+`app-config` file. The URL provided here is for demo docs to use for testing
+purposes.

 To use the demo docs, add the following lines to `app-config.yaml`:

@@ -99,5 +106,5 @@ Open your browser at [http://localhost:3000/docs/](http://localhost:3000/docs/).

 ## Additional reading

- * [Creating and publishing your docs](creating-and-publishing.md)
- * [Back to README](README.md)
+- [Creating and publishing your docs](creating-and-publishing.md)
+- [Back to README](README.md)
@@ -1,4 +1,7 @@
-# Custom App Themes
+---
+id: app-custom-theme
+title: Customize the look-and-feel of your App
+---

 Backstage ships with a default theme with a light and dark mode variant. The
 themes are provided as a part of the
@@ -0,0 +1,6 @@
+---
+id: configure-app-with-plugins
+title: Configuring App with plugins
+---
+
+Coming soon!
@@ -1,4 +1,7 @@
-# Backstage App
+---
+id: create-an-app
+title: Create an App
+---

 To get set up quickly with your own Backstage project you can create a Backstage
 App.
@@ -0,0 +1,6 @@
+---
+id: deployment-k8s
+title: Kubernetes
+---
+
+Coming soon!
@@ -1,4 +1,7 @@
-# Deployment (Other)
+---
+id: deployment-other
+title: Other
+---

 ## Deploying Locally

@@ -1,4 +1,7 @@
-# Development Environment
+---
+id: development-environment
+title: Development Environment
+---

 This section describes how to get set up for doing development on the Backstage
 repository.
@@ -1,6 +1,7 @@
-# Getting started with Backstage
-
-## Running Backstage Locally
+---
+id: index
+title: Running Backstage Locally
+---

 To get up and running with a local Backstage to evaluate it, let's clone it off
 of GitHub and run an initial build. First make sure that you have at least node
@@ -0,0 +1,6 @@
+---
+id: installation
+title: Installation
+---
+
+Coming soon!
@@ -1,4 +1,9 @@
-# Typical Backstage architecture
+---
+id: architecture-overview
+title: Architecture overview
+---
+
+## Overview

 The following diagram shows how Backstage might look when deployed inside a
 company which uses the Tech Radar plugin, the Lighthouse plugin, the Circle CI
@@ -14,27 +19,27 @@ Running this architecture in a real environment typically involves
 containerising the components. Various commands are provided for accomplishing
 this.

-![The architecture of a basic Backstage application](./architecture-overview/backstage-typical-architecture.png)
+![The architecture of a basic Backstage application](../assets/architecture-overview/backstage-typical-architecture.png)

-# The UI
+## The UI

 The UI is a thin, client-side wrapper around a set of plugins. It provides some
 core UI components and libraries for shared activities such as config
 management. [[live demo](https://backstage-demo.roadie.io/)]

-![UI with different components highlighted](./architecture-overview/core-vs-plugin-components-highlighted.png)
+![UI with different components highlighted](../assets/architecture-overview/core-vs-plugin-components-highlighted.png)

 Each plugin typically makes itself available in the UI on a dedicated URL. For
 example, the lighthouse plugin is registered with the UI on `/lighthouse`.
 [[live demo](https://backstage-demo.roadie.io/lighthouse)]

-![The lighthouse plugin UI](./architecture-overview/lighthouse-plugin.png)
+![The lighthouse plugin UI](../assets/architecture-overview/lighthouse-plugin.png)

 The Circle CI plugin is available on `/circleci`.

-![Circle CI Plugin UI](./architecture-overview/circle-ci.png)
+![Circle CI Plugin UI](../assets/architecture-overview/circle-ci.png)

-# Plugins and plugin backends
+## Plugins and plugin backends

 Each plugin is a client side application which mounts itself on the UI. Plugins
 are written in TypeScript or JavaScript. They each live in their own directory
@@ -42,7 +47,7 @@ in `backstage/plugins`. For example, the source code for the lighthouse plugin
 is available at
 [backstage/plugins/lighthouse](https://github.com/spotify/backstage/tree/master/plugins/lighthouse).

-## Installing plugins
+### Installing plugins

 Plugins are typically loaded by the UI in your Backstage applications
 `plugins.ts` file. For example,
@@ -74,7 +79,7 @@ export default builder.build() as ApiHolder;
 As of this moment, there is no config based install procedure for plugins. Some
 code changes are required.

-## Plugin architecture
+### Plugin architecture

 Architecturally, plugins can take three forms:

@@ -82,21 +87,21 @@ Architecturally, plugins can take three forms:
 2. Service backed
 3. Third-party backed

-### Standalone plugins
+#### Standalone plugins

 Standalone plugins run entirely in the browser.
 [The tech radar plugin](https://backstage-demo.roadie.io/tech-radar), for
 example, simply renders hard-coded information. It doesn't make any API requests
 to other services.

-![tech radar plugin ui](./architecture-overview/tech-radar-plugin.png)
+![tech radar plugin ui](../assets/architecture-overview/tech-radar-plugin.png)

 The architecture of the Tech Radar installed into a Backstage app is very
 simple.

-![ui and tech radar plugin connected together](./architecture-overview/tech-radar-plugin-architecture.png)
+![ui and tech radar plugin connected together](../assets/architecture-overview/tech-radar-plugin-architecture.png)

-### Service backed plugins
+#### Service backed plugins

 Service backed plugins make API requests to a service which is within the
 purview of the organisation running Backstage.
@@ -109,7 +114,7 @@ results in a PostgreSQL database.

 Its architecture looks like this:

-![lighthouse plugin backed to microservice and database](./architecture-overview/lighthouse-plugin-architecture.png)
+![lighthouse plugin backed to microservice and database](../assets/architecture-overview/lighthouse-plugin-architecture.png)

 The service catalog in Backstage is another example of a service backed plugin.
 It retrieves a list of services, or "entities", from the Backstage Backend
@@ -131,9 +136,9 @@ Cross Origin Resource Sharing policies which prevent a browser page served at
 [https://example.com](https://example.com) from serving resources hosted at
 https://circleci.com.

-![CircleCi plugin talking to proxy talking to SaaS Circle CI](./architecture-overview/circle-ci-plugin-architecture.png)
+![CircleCi plugin talking to proxy talking to SaaS Circle CI](../assets/architecture-overview/circle-ci-plugin-architecture.png)

-# Databases
+## Databases

 As we have seen, both the lighthouse-audit-service and catalog-backend require a
 database to work with.
@@ -150,7 +155,7 @@ GitHub issues.

 [Update migrations to support postgres by dariddler · Pull Request #1527 · spotify/backstage](https://github.com/spotify/backstage/pull/1527#discussion_r450374145)

-# Containerization
+## Containerization

 The example Backstage architecture shown above would Dockerize into three
 separate docker images.
@@ -159,7 +164,7 @@ separate docker images.
 2. The backend container
 3. The lighthouse audit service container

-![Boxes around the architecture to indicate how it is containerised](./architecture-overview/containerised.png)
+![Boxes around the architecture to indicate how it is containerised](../assets/architecture-overview/containerised.png)

 The frontend container can be built with a provided command.

@@ -1,4 +1,7 @@
-# Architecture and Terminology
+---
+id: architecture-terminology
+title: Architecture terminology
+---

 Backstage is constructed out of three parts. We separate Backstage in this way
 because we see three groups of contributors that work with Backstage in three
@@ -1,4 +1,7 @@
-# Project roadmap
+---
+id: roadmap
+title: Project roadmap
+---

 We created Backstage about 4 years ago. While our internal version of Backstage
 has had the benefit of time to mature and evolve, the first iteration of our
@@ -8,7 +11,7 @@ project and we have already begun work on various aspects of these phases:
 - 🐣 **Phase 1:** Extensible frontend platform (Done ✅) - You will be able to
  easily create a single consistent UI layer for your internal infrastructure
  and tools. A set of reusable
-  [UX patterns and components](http://storybook.backstage.io) help ensure a
+  [UX patterns and components](http://backstage.io/storybook) help ensure a
  consistent experience between tools.

 - 🐢 **Phase 2:** Service Catalog
@@ -1,4 +1,7 @@
-# Support and community
+---
+id: support
+title: Support and community
+---

 - [Discord chatroom](https://discord.gg/MUpMjP2) - Get support or discuss the
  project
--- a/Show More
+++ b/Show More