feat: the whole docs structure

Co-authored-by: Raghunandan Balachandran <[email protected]>
Co-authored-by: Ben Lambert <[email protected]>

CONTRIBUTING.md

@@ -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.
 

README.md

@@ -1,4 +1,4 @@
-![headline](docs/headline.png)
+![headline](docs/assets/headline.png)
 
 # [Backstage](https://backstage.io)
 

docs/FAQ.md

@@ -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,18 +138,26 @@ 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?
 
 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.

docs/api/backend.md

@@ -0,0 +1,6 @@
+---
+id: backend
+title: Backend
+---
+
+## TODO

docs/api/utility-apis.md

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

docs/architecture-decisions/adr001-add-adr-log.md

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

docs/architecture-decisions/adr002-default-catalog-file-format.md

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

docs/architecture-decisions/adr003-avoid-default-exports.md

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

docs/architecture-decisions/adr004-module-export-structure.md

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

docs/architecture-decisions/adr005-catalog-core-entities.md

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

docs/architecture-decisions/adr006-avoid-react-fc.md

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

docs/architecture-decisions/adr007-use-msw-to-mock-service-requests.md

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

docs/architecture-decisions/adr008-default-catalog-file-name.md

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

docs/architecture-decisions/index.md

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

docs/dls/contributing-to-storybook.md

@@ -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,12 +32,12 @@ 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._
 
 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)

docs/dls/design.md

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

docs/dls/figma.md

@@ -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.

docs/features/software-catalog/descriptor-format.md

@@ -84,7 +84,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.

docs/features/software-catalog/extending-the-model.md

@@ -2,3 +2,5 @@
 id: extending-the-model
 title: Extending the model
 ---
+
+TODO

docs/features/software-catalog/external-integrations.md

@@ -2,3 +2,5 @@
 id: external-integrations
 title: External integrations
 ---
+
+TODO

docs/features/software-catalog/index.md

@@ -26,7 +26,7 @@ can be organised around the entities in the catalog.
 
 TODO
 
-![](service-catalog-home.png)
+![](../../assets/software-catalog/service-catalog-home.png)
 
 ## Links