Merge pull request #1908 from spotify/mob/docusaurus-structure

docs: start bringing structure from /docs to docusaurus
2020-08-13 15:41:02 +02:00
parent 266d70cd8c c6655b1e73
commit b9d61d7784
111 changed files with 3958 additions and 1930 deletions
@@ -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
@@ -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.

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

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

@@ -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](/docs/FAQ.md#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](/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.)

 ### 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?](/docs/FAQ.md#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,98 +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)
-      - [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://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)
@@ -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,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

@@ -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://storybook.backstage.io](http://storybook.backstage.io)

 ## 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

@@ -110,12 +115,13 @@ picked up by our team as something to be added to our design system.
 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.

@@ -82,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.
@@ -1,4 +1,7 @@
-# Extending the model
+---
+id: extending-the-model
+title: Extending the model
+---

 Backstage natively supports tracking of the following component
 [`type`](descriptor-format.md)'s:
@@ -1,4 +1,7 @@
-# External integrations
+---
+id: external-integrations
+title: External integrations
+---

 Backstage natively supports storing software components in
 [metadata YAML files](descriptor-format.md). However, companies that already
@@ -1,4 +1,7 @@
-# Backstage Service Catalog (alpha)
+---
+id: software-catalog-overview
+title: Backstage Service Catalog (alpha)
+---

 ## What is a Service Catalog?

@@ -32,7 +35,7 @@ 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`.

-![](service-catalog-home.png)
+![](../../assets/software-catalog/service-catalog-home.png)

 ## Adding components to the catalog

@@ -1,4 +1,7 @@
-# Backstage System Model
+---
+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.
@@ -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,4 +1,7 @@
-# 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
@@ -18,7 +21,7 @@ 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

@@ -27,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 `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)
@@ -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?

@@ -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
@@ -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
@@ -1,9 +1,10 @@
-# [Backstage](https://backstage.io)
+---
+id: what-is-backstage
+title: What is Backstage?
+---

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

-## What is Backstage?
-
 [Backstage](https://backstage.io/) is an open platform for building developer
 portals. Powered by a centralized service catalog, Backstage restores order to
 your microservices and infrastructure. So your product teams can ship
@@ -0,0 +1,6 @@
+---
+id: backend-plugin
+title: Backend plugin
+---
+
+## TODO
@@ -0,0 +1,6 @@
+---
+id: call-existing-api
+title: Call existing API
+---
+
+## TODO
@@ -1,4 +1,7 @@
-# Create a Backstage Plugin
+---
+id: create-a-plugin
+title: Create a Backstage Plugin
+---

 A Backstage Plugin adds functionality to Backstage.

@@ -1,4 +1,7 @@
-# Existing plugins
+---
+id: existing-plugins
+title: Existing plugins
+---

 ## Open source plugins

@@ -1,4 +1,7 @@
-# Plugins
+---
+id: index
+title: Intro
+---

 Backstage is a single-page application composed of a set of plugins.

@@ -8,7 +11,7 @@ development tool as a plugin in Backstage. By following strong
 [design guidelines](../dls/design.md) we ensure the the overall user experience
 stays consistent between plugins.

-![plugin](my-plugin_screenshot.png)
+![plugin](../assets/my-plugin_screenshot.png)

 ## Creating a plugin

@@ -1,4 +1,7 @@
-# Plugin Development in Backstage
+---
+id: plugin-development
+title: Plugin Development in Backstage
+---

 Backstage plugins provide features to a Backstage App.

@@ -0,0 +1,6 @@
+---
+id: proxying
+title: Proxying
+---
+
+## TODO
@@ -0,0 +1,6 @@
+---
+id: publish-private
+title: Publish private
+---
+
+## TODO
@@ -1,4 +1,7 @@
-# Publishing
+---
+id: publishing
+title: Publishing
+---

 ## NPM

@@ -1,4 +1,7 @@
-# Structure of a Plugin
+---
+id: structure-of-a-plugin
+title: Structure of a Plugin
+---

 Nice, you have a new plugin! We'll soon see how we can develop it into doing
 great things. But first off, let's look at what we get out of the box.
@@ -1,4 +1,7 @@
-# Testing with Jest
+---
+id: testing
+title: Testing with Jest
+---

 Backstage uses [Jest](https://facebook.github.io/jest/) for all our unit testing
 needs.
@@ -1,4 +1,7 @@
-# createPlugin - feature flags
+---
+id: createPlugin-feature-flags
+title: createPlugin - feature flags
+---

 The `featureFlags` object passed to the `register` function makes it possible
 for plugins to register Feature Flags in Backstage for users to opt into. You
@@ -1,4 +1,7 @@
-# createPlugin - router
+---
+id: createPlugin-router
+title: createPlugin - router
+---

 The router that is passed to the `register` function makes it possible for
 plugins to hook into routing of the Backstage app and provide the end users with
--- a/Show More
+++ b/Show More