diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cf7622d692d80..3c1db8fc476f7 100644 --- a/CONTRIBUTING.md +++ b/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. diff --git a/README.md b/README.md index 56932a17419c5..3a4af2723f2c1 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -![headline](docs/headline.png) +![headline](docs/assets/headline.png) # [Backstage](https://backstage.io) diff --git a/docs/FAQ.md b/docs/FAQ.md index 7d568a840e3d8..5d10e9c7d0458 100644 --- a/docs/FAQ.md +++ b/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,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. diff --git a/docs/api/backend.md b/docs/api/backend.md index e69de29bb2d1d..bc44b8350c10f 100644 --- a/docs/api/backend.md +++ b/docs/api/backend.md @@ -0,0 +1,6 @@ +--- +id: backend +title: Backend +--- + +## TODO diff --git a/docs/api/utility-apis.md b/docs/api/utility-apis.md index f87db15e7edc8..ff8c91e178df5 100644 --- a/docs/api/utility-apis.md +++ b/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 fooApiRef.
-Figure showing the relationship between utility APIs, the apps that provide them, and the plugins that consume them +Figure showing the relationship between utility APIs, the apps that provide them, and the plugins that consume them
The current method for connecting Utility API providers and consumers is via the diff --git a/docs/architecture-decisions/adr001-add-adr-log.md b/docs/architecture-decisions/adr001-add-adr-log.md index e6ab39aea46cc..8a484fa264423 100644 --- a/docs/architecture-decisions/adr001-add-adr-log.md +++ b/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 | | ---------- | ------ | diff --git a/docs/architecture-decisions/adr002-default-catalog-file-format.md b/docs/architecture-decisions/adr002-default-catalog-file-format.md index 00c8b0947da2b..c1cb719bf5ee9 100644 --- a/docs/architecture-decisions/adr002-default-catalog-file-format.md +++ b/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 | | ---------- | ------ | diff --git a/docs/architecture-decisions/adr003-avoid-default-exports.md b/docs/architecture-decisions/adr003-avoid-default-exports.md index 7becebaa4b683..7a8df28f4935e 100644 --- a/docs/architecture-decisions/adr003-avoid-default-exports.md +++ b/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 | | ---------- | ------ | diff --git a/docs/architecture-decisions/adr004-module-export-structure.md b/docs/architecture-decisions/adr004-module-export-structure.md index 54132773c9ae3..077f8c35d1e74 100644 --- a/docs/architecture-decisions/adr004-module-export-structure.md +++ b/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 | | ---------- | ------ | diff --git a/docs/architecture-decisions/adr005-catalog-core-entities.md b/docs/architecture-decisions/adr005-catalog-core-entities.md index d607dc62fbaa5..8f39acd1cf43e 100644 --- a/docs/architecture-decisions/adr005-catalog-core-entities.md +++ b/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 diff --git a/docs/architecture-decisions/adr006-avoid-react-fc.md b/docs/architecture-decisions/adr006-avoid-react-fc.md index 21e6d5b637dbc..e48fceb5629ff 100644 --- a/docs/architecture-decisions/adr006-avoid-react-fc.md +++ b/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 diff --git a/docs/architecture-decisions/adr007-use-msw-to-mock-service-requests.md b/docs/architecture-decisions/adr007-use-msw-to-mock-service-requests.md index bdb221cea3d96..773f08be3004c 100644 --- a/docs/architecture-decisions/adr007-use-msw-to-mock-service-requests.md +++ b/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 diff --git a/docs/architecture-decisions/adr008-default-catalog-file-name.md b/docs/architecture-decisions/adr008-default-catalog-file-name.md index 23910f634f0a4..979ea4de33d14 100644 --- a/docs/architecture-decisions/adr008-default-catalog-file-name.md +++ b/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 diff --git a/docs/architecture-decisions/index.md b/docs/architecture-decisions/index.md index 7762a9c827bc5..b02e8deabb1da 100644 --- a/docs/architecture-decisions/index.md +++ b/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 diff --git a/docs/architecture-decisions/catalog-core-entities.png b/docs/assets/architecture-decisions/catalog-core-entities.png similarity index 100% rename from docs/architecture-decisions/catalog-core-entities.png rename to docs/assets/architecture-decisions/catalog-core-entities.png diff --git a/docs/overview/architecture-overview/backstage-typical-architecture.png b/docs/assets/architecture-overview/backstage-typical-architecture.png similarity index 100% rename from docs/overview/architecture-overview/backstage-typical-architecture.png rename to docs/assets/architecture-overview/backstage-typical-architecture.png diff --git a/docs/overview/architecture-overview/circle-ci-plugin-architecture.png b/docs/assets/architecture-overview/circle-ci-plugin-architecture.png similarity index 100% rename from docs/overview/architecture-overview/circle-ci-plugin-architecture.png rename to docs/assets/architecture-overview/circle-ci-plugin-architecture.png diff --git a/docs/overview/architecture-overview/circle-ci.png b/docs/assets/architecture-overview/circle-ci.png similarity index 100% rename from docs/overview/architecture-overview/circle-ci.png rename to docs/assets/architecture-overview/circle-ci.png diff --git a/docs/overview/architecture-overview/containerised.png b/docs/assets/architecture-overview/containerised.png similarity index 100% rename from docs/overview/architecture-overview/containerised.png rename to docs/assets/architecture-overview/containerised.png diff --git a/docs/overview/architecture-overview/core-vs-plugin-components-highlighted.png b/docs/assets/architecture-overview/core-vs-plugin-components-highlighted.png similarity index 100% rename from docs/overview/architecture-overview/core-vs-plugin-components-highlighted.png rename to docs/assets/architecture-overview/core-vs-plugin-components-highlighted.png diff --git a/docs/overview/architecture-overview/lighthouse-plugin-architecture.png b/docs/assets/architecture-overview/lighthouse-plugin-architecture.png similarity index 100% rename from docs/overview/architecture-overview/lighthouse-plugin-architecture.png rename to docs/assets/architecture-overview/lighthouse-plugin-architecture.png diff --git a/docs/overview/architecture-overview/lighthouse-plugin.png b/docs/assets/architecture-overview/lighthouse-plugin.png similarity index 100% rename from docs/overview/architecture-overview/lighthouse-plugin.png rename to docs/assets/architecture-overview/lighthouse-plugin.png diff --git a/docs/overview/architecture-overview/tech-radar-plugin-architecture.png b/docs/assets/architecture-overview/tech-radar-plugin-architecture.png similarity index 100% rename from docs/overview/architecture-overview/tech-radar-plugin-architecture.png rename to docs/assets/architecture-overview/tech-radar-plugin-architecture.png diff --git a/docs/overview/architecture-overview/tech-radar-plugin.png b/docs/assets/architecture-overview/tech-radar-plugin.png similarity index 100% rename from docs/overview/architecture-overview/tech-radar-plugin.png rename to docs/assets/architecture-overview/tech-radar-plugin.png diff --git a/docs/dls/DLS.png b/docs/assets/dls/DLS.png similarity index 100% rename from docs/dls/DLS.png rename to docs/assets/dls/DLS.png diff --git a/docs/dls/designheader.png b/docs/assets/dls/designheader.png similarity index 100% rename from docs/dls/designheader.png rename to docs/assets/dls/designheader.png diff --git a/docs/dls/running-storybook.png b/docs/assets/dls/running-storybook.png similarity index 100% rename from docs/dls/running-storybook.png rename to docs/assets/dls/running-storybook.png diff --git a/docs/dls/storybook-page.png b/docs/assets/dls/storybook-page.png similarity index 100% rename from docs/dls/storybook-page.png rename to docs/assets/dls/storybook-page.png diff --git a/docs/features/software-catalog/service-catalog-home.png b/docs/assets/software-catalog/service-catalog-home.png similarity index 100% rename from docs/features/software-catalog/service-catalog-home.png rename to docs/assets/software-catalog/service-catalog-home.png diff --git a/docs/features/software-templates/assets/added-to-the-catalog-list.png b/docs/assets/software-templates/added-to-the-catalog-list.png similarity index 100% rename from docs/features/software-templates/assets/added-to-the-catalog-list.png rename to docs/assets/software-templates/added-to-the-catalog-list.png diff --git a/docs/features/software-templates/assets/complete.png b/docs/assets/software-templates/complete.png similarity index 100% rename from docs/features/software-templates/assets/complete.png rename to docs/assets/software-templates/complete.png diff --git a/docs/features/software-templates/assets/create.png b/docs/assets/software-templates/create.png similarity index 100% rename from docs/features/software-templates/assets/create.png rename to docs/assets/software-templates/create.png diff --git a/docs/features/software-templates/assets/failed.png b/docs/assets/software-templates/failed.png similarity index 100% rename from docs/features/software-templates/assets/failed.png rename to docs/assets/software-templates/failed.png diff --git a/docs/features/software-templates/assets/go-to-catalog.png b/docs/assets/software-templates/go-to-catalog.png similarity index 100% rename from docs/features/software-templates/assets/go-to-catalog.png rename to docs/assets/software-templates/go-to-catalog.png diff --git a/docs/features/software-templates/assets/running.png b/docs/assets/software-templates/running.png similarity index 100% rename from docs/features/software-templates/assets/running.png rename to docs/assets/software-templates/running.png diff --git a/docs/features/software-templates/assets/template-picked-2.png b/docs/assets/software-templates/template-picked-2.png similarity index 100% rename from docs/features/software-templates/assets/template-picked-2.png rename to docs/assets/software-templates/template-picked-2.png diff --git a/docs/features/software-templates/assets/template-picked.png b/docs/assets/software-templates/template-picked.png similarity index 100% rename from docs/features/software-templates/assets/template-picked.png rename to docs/assets/software-templates/template-picked.png diff --git a/docs/api/utility-apis-fig1.svg b/docs/assets/utility-apis-fig1.svg similarity index 100% rename from docs/api/utility-apis-fig1.svg rename to docs/assets/utility-apis-fig1.svg diff --git a/docs/dls/contributing-to-storybook.md b/docs/dls/contributing-to-storybook.md index 7dbe72f6d3623..6546073ef7e99 100644 --- a/docs/dls/contributing-to-storybook.md +++ b/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,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) diff --git a/docs/dls/design.md b/docs/dls/design.md index d773a07a8fe84..45b7b973edd0a 100644 --- a/docs/dls/design.md +++ b/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 diff --git a/docs/dls/figma.md b/docs/dls/figma.md index 8fe6ea8d0f7f6..14de2f598038e 100644 --- a/docs/dls/figma.md +++ b/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. diff --git a/docs/features/software-catalog/descriptor-format.md b/docs/features/software-catalog/descriptor-format.md index 3f0503f2abd90..ea10d6b720793 100644 --- a/docs/features/software-catalog/descriptor-format.md +++ b/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. diff --git a/docs/features/software-catalog/extending-the-model.md b/docs/features/software-catalog/extending-the-model.md index 9162c45133717..093a7887410a2 100644 --- a/docs/features/software-catalog/extending-the-model.md +++ b/docs/features/software-catalog/extending-the-model.md @@ -2,3 +2,5 @@ id: extending-the-model title: Extending the model --- + +TODO diff --git a/docs/features/software-catalog/external-integrations.md b/docs/features/software-catalog/external-integrations.md index ef5e6a780634b..5f4df979401d9 100644 --- a/docs/features/software-catalog/external-integrations.md +++ b/docs/features/software-catalog/external-integrations.md @@ -2,3 +2,5 @@ id: external-integrations title: External integrations --- + +TODO diff --git a/docs/features/software-catalog/index.md b/docs/features/software-catalog/index.md index d1c4d51d60671..ce27d821d772d 100644 --- a/docs/features/software-catalog/index.md +++ b/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 diff --git a/docs/features/software-catalog/system-model.md b/docs/features/software-catalog/system-model.md index 2fcf4e3c6834f..7f134d4f4861c 100644 --- a/docs/features/software-catalog/system-model.md +++ b/docs/features/software-catalog/system-model.md @@ -2,3 +2,5 @@ id: system-model title: System Model --- + +TODO diff --git a/docs/features/software-templates/extending/index.md b/docs/features/software-templates/extending/index.md index bc9bc4d85af06..21d8befda1d42 100644 --- a/docs/features/software-templates/extending/index.md +++ b/docs/features/software-templates/extending/index.md @@ -1,7 +1,6 @@ --- id: extending-index title: Extending the Scaffolder -sidebar_label: Overview --- Welcome. Take a seat. You're at the Scaffolder Documentation. diff --git a/docs/features/software-templates/index.md b/docs/features/software-templates/index.md index fe58b5064bf74..72d12b10ccd18 100644 --- a/docs/features/software-templates/index.md +++ b/docs/features/software-templates/index.md @@ -16,7 +16,7 @@ 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 @@ -25,38 +25,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`. -![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) diff --git a/docs/features/techdocs/concepts.md b/docs/features/techdocs/concepts.md index f77747078cd2a..fd875439946bc 100644 --- a/docs/features/techdocs/concepts.md +++ b/docs/features/techdocs/concepts.md @@ -12,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 @@ -21,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) @@ -32,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 @@ -44,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 @@ -53,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) diff --git a/docs/getting-started/configure-app-with-plugins.md b/docs/getting-started/configure-app-with-plugins.md index cab3a0d1d2e87..a0d2c27f8972d 100644 --- a/docs/getting-started/configure-app-with-plugins.md +++ b/docs/getting-started/configure-app-with-plugins.md @@ -2,3 +2,5 @@ id: configure-app-with-plugins title: Configuring App with plugins --- + +Coming soon! diff --git a/docs/getting-started/deployment-k8s.md b/docs/getting-started/deployment-k8s.md index 9d63d8c6eb8a5..2a184779e2762 100644 --- a/docs/getting-started/deployment-k8s.md +++ b/docs/getting-started/deployment-k8s.md @@ -2,3 +2,5 @@ id: deployment-k8s title: Kubernetes --- + +Coming soon! diff --git a/docs/overview/architecture-overview.md b/docs/overview/architecture-overview.md index d5e5761b70472..9f1d6d3291cc7 100644 --- a/docs/overview/architecture-overview.md +++ b/docs/overview/architecture-overview.md @@ -3,7 +3,7 @@ id: architecture-overview title: Architecture overview --- -# Typical Backstage architecture +## 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 @@ -19,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 @@ -47,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, @@ -79,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: @@ -87,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. @@ -114,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 @@ -136,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. @@ -155,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. @@ -164,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. diff --git a/docs/overview/architecture-terminology.md b/docs/overview/architecture-terminology.md index 2877a2aa66603..aee581f9275f3 100644 --- a/docs/overview/architecture-terminology.md +++ b/docs/overview/architecture-terminology.md @@ -3,8 +3,6 @@ id: architecture-terminology title: Architecture terminology --- -# Architecture and 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 different ways. diff --git a/docs/overview/roadmap.md b/docs/overview/roadmap.md index ef313b55ad728..125f8cce7bb28 100644 --- a/docs/overview/roadmap.md +++ b/docs/overview/roadmap.md @@ -3,8 +3,6 @@ id: roadmap title: Project roadmap --- -# 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 open source version is still nascent. We are envisioning three phases of the diff --git a/docs/overview/support.md b/docs/overview/support.md index 7c7390fb6925b..9e4e9eca15a3c 100644 --- a/docs/overview/support.md +++ b/docs/overview/support.md @@ -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 diff --git a/docs/plugins/index.md b/docs/plugins/index.md index 514212b2de0ca..bb8951f95950c 100644 --- a/docs/plugins/index.md +++ b/docs/plugins/index.md @@ -11,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](assets/my-plugin_screenshot.png) +![plugin](../assets/my-plugin_screenshot.png) ## Creating a plugin diff --git a/docs/reference/createPlugin-feature-flags.md b/docs/reference/createPlugin-feature-flags.md index 0f1debd515924..bc38656939e85 100644 --- a/docs/reference/createPlugin-feature-flags.md +++ b/docs/reference/createPlugin-feature-flags.md @@ -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 diff --git a/docs/reference/createPlugin-router.md b/docs/reference/createPlugin-router.md index 831b27f3886b1..ebefa13bb0879 100644 --- a/docs/reference/createPlugin-router.md +++ b/docs/reference/createPlugin-router.md @@ -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 diff --git a/docs/reference/createPlugin.md b/docs/reference/createPlugin.md index 7ecb6d461ac5c..0cabe63b39734 100644 --- a/docs/reference/createPlugin.md +++ b/docs/reference/createPlugin.md @@ -1,4 +1,7 @@ -# createPlugin +--- +id: createPlugin +title: createPlugin +--- Taking a plugin config as argument and returns a new plugin. diff --git a/docs/reference/utility-apis/README.md b/docs/reference/utility-apis/README.md index 8b9ebcbdad4df..fbfbbc475e4aa 100644 --- a/docs/reference/utility-apis/README.md +++ b/docs/reference/utility-apis/README.md @@ -1,11 +1,14 @@ -# Backstage Core Utility APIs +--- +id: README +title: Utility API References +--- The following is a list of all Utility APIs defined by `@backstage/core`. They are available to use by plugins and components, and can be accessed using the `useApi` hook, also provided by `@backstage/core`. For more information, see https://github.com/spotify/backstage/blob/master/docs/api/utility-apis.md. -### alert +## alert Used to report alerts and forward them to the app @@ -14,7 +17,7 @@ Implemented type: [AlertApi](./AlertApi.md) ApiRef: [alertApiRef](https://github.com/spotify/backstage/blob/f8780ff32509d0326bc513791ea60846d7614b34/packages/core-api/src/apis/definitions/AlertApi.ts#L41) -### appTheme +## appTheme API Used to configure the app theme, and enumerate options @@ -23,7 +26,7 @@ Implemented type: [AppThemeApi](./AppThemeApi.md) ApiRef: [appThemeApiRef](https://github.com/spotify/backstage/blob/f8780ff32509d0326bc513791ea60846d7614b34/packages/core-api/src/apis/definitions/AppThemeApi.ts#L74) -### config +## config Used to access runtime configuration @@ -32,7 +35,7 @@ Implemented type: [Config](./Config.md) ApiRef: [configApiRef](https://github.com/spotify/backstage/blob/f8780ff32509d0326bc513791ea60846d7614b34/packages/core-api/src/apis/definitions/ConfigApi.ts#L22) -### error +## error Used to report errors and forward them to the app @@ -41,7 +44,7 @@ Implemented type: [ErrorApi](./ErrorApi.md) ApiRef: [errorApiRef](https://github.com/spotify/backstage/blob/f8780ff32509d0326bc513791ea60846d7614b34/packages/core-api/src/apis/definitions/ErrorApi.ts#L65) -### featureFlags +## featureFlags Used to toggle functionality in features across Backstage @@ -50,7 +53,7 @@ Implemented type: [FeatureFlagsApi](./FeatureFlagsApi.md) ApiRef: [featureFlagsApiRef](https://github.com/spotify/backstage/blob/f8780ff32509d0326bc513791ea60846d7614b34/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L58) -### githubAuth +## githubAuth Provides authentication towards Github APIs @@ -62,7 +65,7 @@ Implemented types: [OAuthApi](./OAuthApi.md), ApiRef: [githubAuthApiRef](https://github.com/spotify/backstage/blob/f8780ff32509d0326bc513791ea60846d7614b34/packages/core-api/src/apis/definitions/auth.ts#L230) -### gitlabAuth +## gitlabAuth Provides authentication towards Gitlab APIs @@ -74,7 +77,7 @@ Implemented types: [OAuthApi](./OAuthApi.md), ApiRef: [gitlabAuthApiRef](https://github.com/spotify/backstage/blob/f8780ff32509d0326bc513791ea60846d7614b34/packages/core-api/src/apis/definitions/auth.ts#L260) -### googleAuth +## googleAuth Provides authentication towards Google APIs and identities @@ -87,7 +90,7 @@ Implemented types: [OAuthApi](./OAuthApi.md), ApiRef: [googleAuthApiRef](https://github.com/spotify/backstage/blob/f8780ff32509d0326bc513791ea60846d7614b34/packages/core-api/src/apis/definitions/auth.ts#L213) -### identity +## identity Provides access to the identity of the signed in user @@ -96,7 +99,7 @@ Implemented type: [IdentityApi](./IdentityApi.md) ApiRef: [identityApiRef](https://github.com/spotify/backstage/blob/f8780ff32509d0326bc513791ea60846d7614b34/packages/core-api/src/apis/definitions/IdentityApi.ts#L54) -### oauth2 +## oauth2 Example of how to use oauth2 custom provider @@ -107,7 +110,7 @@ Implemented types: [OAuthApi](./OAuthApi.md), ApiRef: [oauth2ApiRef](https://github.com/spotify/backstage/blob/f8780ff32509d0326bc513791ea60846d7614b34/packages/core-api/src/apis/definitions/auth.ts#L270) -### oauthRequest +## oauthRequest An API for implementing unified OAuth flows in Backstage @@ -116,7 +119,7 @@ Implemented type: [OAuthRequestApi](./OAuthRequestApi.md) ApiRef: [oauthRequestApiRef](https://github.com/spotify/backstage/blob/f8780ff32509d0326bc513791ea60846d7614b34/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L130) -### oktaAuth +## oktaAuth Provides authentication towards Okta APIs @@ -129,7 +132,7 @@ Implemented types: [OAuthApi](./OAuthApi.md), ApiRef: [oktaAuthApiRef](https://github.com/spotify/backstage/blob/f8780ff32509d0326bc513791ea60846d7614b34/packages/core-api/src/apis/definitions/auth.ts#L243) -### storage +## storage Provides the ability to store data which is unique to the user diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md index e69de29bb2d1d..b5780875b227e 100644 --- a/docs/tutorials/index.md +++ b/docs/tutorials/index.md @@ -0,0 +1,6 @@ +--- +id: index +title: Overview +--- + +## Coming soon! diff --git a/docs/verify-links.js b/docs/verify-links.js index 8c865309f9cef..f0413e1656c5d 100755 --- a/docs/verify-links.js +++ b/docs/verify-links.js @@ -65,7 +65,12 @@ async function verifyFile(filePath) { async function main() { process.chdir(projectRoot); - const files = await recursive('.', ['node_modules', 'dist', 'bin']); + const files = await recursive('.', [ + 'node_modules', + 'dist', + 'bin', + 'microsite', + ]); const mdFiles = files.filter(f => f.endsWith('.md')); const badUrls = []; diff --git a/microsite/blog/2020-04-30-how-to-quickly-set-up-backstage.md b/microsite/blog/2020-04-30-how-to-quickly-set-up-backstage.md index b4fe534a67ea6..7b1fbb2d11ba4 100644 --- a/microsite/blog/2020-04-30-how-to-quickly-set-up-backstage.md +++ b/microsite/blog/2020-04-30-how-to-quickly-set-up-backstage.md @@ -50,7 +50,7 @@ yarn start And you are good to go! 👍 -Read the full documentation on how to [create an app](https://github.com/spotify/backstage/blob/master/docs/create-an-app.md) on GitHub. +Read the full documentation on how to [create an app](https://github.com/spotify/backstage/blob/master/docs/getting-started/create-an-app.md) on GitHub. ## What do I get? (Let's get technical...) diff --git a/microsite/i18n/en.json b/microsite/i18n/en.json index 97eb32ac55a3a..c3faa0874a9ce 100644 --- a/microsite/i18n/en.json +++ b/microsite/i18n/en.json @@ -6,73 +6,82 @@ "tagline": "An open platform for building developer portals", "docs": { "api/backend": { - "title": "api/backend" + "title": "Backend" }, "api/utility-apis": { - "title": "api/utility-apis" + "title": "Utility APIs" }, - "architecture-decisions/adr001-add-adr-log": { - "title": "architecture-decisions/adr001-add-adr-log" + "architecture-decisions/adrs-adr001": { + "title": "ADR001: Architecture Decision Record (ADR) log", + "sidebar_label": "ADR001" }, - "architecture-decisions/adr002-default-catalog-file-format": { - "title": "architecture-decisions/adr002-default-catalog-file-format" + "architecture-decisions/adrs-adr002": { + "title": "ADR002: Default Software Catalog File Format", + "sidebar_label": "ADR002" }, - "architecture-decisions/adr003-avoid-default-exports": { - "title": "architecture-decisions/adr003-avoid-default-exports" + "architecture-decisions/adrs-adr003": { + "title": "ADR003: Avoid Default Exports and Prefer Named Exports", + "sidebar_label": "ADR003" }, - "architecture-decisions/adr004-module-export-structure": { - "title": "architecture-decisions/adr004-module-export-structure" + "architecture-decisions/adrs-adr004": { + "title": "ADR004: Module Export Structure", + "sidebar_label": "ADR004" }, - "architecture-decisions/adr005-catalog-core-entities": { - "title": "architecture-decisions/adr005-catalog-core-entities" + "architecture-decisions/adrs-adr005": { + "title": "ADR005: Catalog Core Entities", + "sidebar_label": "ADR005" }, - "architecture-decisions/adr006-avoid-react-fc": { - "title": "architecture-decisions/adr006-avoid-react-fc" + "architecture-decisions/adrs-adr006": { + "title": "ADR006: Avoid React.FC and React.SFC", + "sidebar_label": "ADR006" }, - "architecture-decisions/adr007-use-msw-to-mock-service-requests": { - "title": "architecture-decisions/adr007-use-msw-to-mock-service-requests" + "architecture-decisions/adrs-adr007": { + "title": "ADR007: Use MSW to mock http requests", + "sidebar_label": "ADR007" }, - "architecture-decisions/adr008-default-catalog-file-name": { - "title": "architecture-decisions/adr008-default-catalog-file-name" + "architecture-decisions/adrs-adr008": { + "title": "ADR008: Default Catalog File Name", + "sidebar_label": "ADR008" }, - "architecture-decisions/index": { - "title": "architecture-decisions/index" + "architecture-decisions/adrs-overview": { + "title": "Architecture Decision Records (ADR)", + "sidebar_label": "Overview" }, "auth/add-auth-provider": { - "title": "auth/add-auth-provider" + "title": "Adding authentication providers" }, "auth/auth-backend": { - "title": "auth/auth-backend" + "title": "Auth backend" }, "auth/glossary": { - "title": "auth/glossary" + "title": "Glossary" }, "auth/index": { - "title": "auth/index" + "title": "User Authentication and Authorization in Backstage" }, "auth/oauth": { - "title": "auth/oauth" + "title": "OAuth and OpenID Connect" }, "conf/defining": { - "title": "conf/defining" + "title": "Defining Configuration for your Plugin" }, "conf/index": { - "title": "conf/index" + "title": "Static Configuration in Backstage" }, "conf/reading": { - "title": "conf/reading" + "title": "Reading Backstage Configuration" }, "conf/writing": { - "title": "conf/writing" + "title": "Writing Backstage Configuration Files" }, "dls/contributing-to-storybook": { - "title": "dls/contributing-to-storybook" + "title": "Contributing to Storybook" }, "dls/design": { - "title": "dls/design" + "title": "Design" }, "dls/figma": { - "title": "dls/figma" + "title": "Figma" }, "FAQ": { "title": "FAQ" @@ -85,10 +94,10 @@ "sidebar_label": "YAML File Format" }, "features/software-catalog/extending-the-model": { - "title": "features/software-catalog/extending-the-model" + "title": "Extending the model" }, "features/software-catalog/external-integrations": { - "title": "features/software-catalog/external-integrations" + "title": "External integrations" }, "features/software-catalog/software-catalog-overview": { "title": "Backstage Service Catalog (alpha)" @@ -97,7 +106,7 @@ "title": "features/software-catalog/populating" }, "features/software-catalog/system-model": { - "title": "features/software-catalog/system-model" + "title": "System Model" }, "features/software-templates/adding-templates": { "title": "Adding your own Templates" @@ -118,31 +127,34 @@ "title": "Software Templates" }, "features/techdocs/concepts": { - "title": "features/techdocs/concepts" + "title": "Concepts" }, "features/techdocs/creating-and-publishing": { - "title": "features/techdocs/creating-and-publishing" + "title": "Creating and publishing your docs", + "sidebar_label": "Creating and Publishing Documentation" }, - "features/techdocs/FAQ": { - "title": "features/techdocs/FAQ" + "features/techdocs/faqs": { + "title": "TechDocs FAQ", + "sidebar_label": "FAQ" }, "features/techdocs/getting-started": { - "title": "features/techdocs/getting-started" + "title": "Getting Started" }, "features/techdocs/techdocs-overview": { - "title": "TechDocs Documentation" + "title": "TechDocs Documentation", + "sidebar_label": "Overview" }, "getting-started/app-custom-theme": { "title": "Customize the look-and-feel of your App" }, "getting-started/configure-app-with-plugins": { - "title": "getting-started/configure-app-with-plugins" + "title": "Configuring App with plugins" }, "getting-started/create-an-app": { "title": "Create an App" }, "getting-started/deployment-k8s": { - "title": "getting-started/deployment-k8s" + "title": "Kubernetes" }, "getting-started/deployment-other": { "title": "Other" @@ -169,7 +181,7 @@ "title": "Project roadmap" }, "overview/support": { - "title": "overview/support" + "title": "Support and community" }, "overview/what-is-backstage": { "title": "What is Backstage?" @@ -211,13 +223,13 @@ "title": "README" }, "reference/createPlugin-feature-flags": { - "title": "reference/createPlugin-feature-flags" + "title": "createPlugin - feature flags" }, "reference/createPlugin-router": { - "title": "reference/createPlugin-router" + "title": "createPlugin - router" }, "reference/createPlugin": { - "title": "reference/createPlugin" + "title": "createPlugin" }, "reference/utility-apis/AlertApi": { "title": "reference/utility-apis/AlertApi" @@ -253,7 +265,7 @@ "title": "reference/utility-apis/ProfileInfoApi" }, "reference/utility-apis/README": { - "title": "reference/utility-apis/README" + "title": "Utility API References" }, "reference/utility-apis/SessionStateApi": { "title": "reference/utility-apis/SessionStateApi" @@ -262,7 +274,7 @@ "title": "reference/utility-apis/StorageApi" }, "tutorials/index": { - "title": "tutorials/index" + "title": "Overview" } }, "links": { @@ -277,7 +289,16 @@ "Overview": "Overview", "Getting Started": "Getting Started", "Features": "Features", - "Plugins": "Plugins" + "Plugins": "Plugins", + "Configuration": "Configuration", + "Auth and identity": "Auth and identity", + "Designing for Backstage": "Designing for Backstage", + "API references": "API references", + "Tutorials": "Tutorials", + "Architecture Decision Records (ADRs)": "Architecture Decision Records (ADRs)", + "Contribute": "Contribute", + "Support": "Support", + "FAQ": "FAQ" } }, "pages-strings": { diff --git a/microsite/sidebars.json b/microsite/sidebars.json index a32cd9d0953a4..c8b335660e6f9 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -48,16 +48,10 @@ "ids": [ "features/software-templates/software-templates-index", "features/software-templates/adding-templates", - { - "type": "subcategory", - "label": "Extending the Scaffolder", - "ids": [ - "features/software-templates/extending/extending-index", - "features/software-templates/extending/extending-templater", - "features/software-templates/extending/extending-publisher", - "features/software-templates/extending/extending-preparer" - ] - } + "features/software-templates/extending/extending-index", + "features/software-templates/extending/extending-templater", + "features/software-templates/extending/extending-publisher", + "features/software-templates/extending/extending-preparer" ] }, { @@ -65,10 +59,10 @@ "label": "Docs-like-code", "ids": [ "features/techdocs/techdocs-overview", - "features/techdocs/techdocs-getting-started", - "features/techdocs/techdocs-concepts", - "features/techdocs/techdocs-creating-and-publishing", - "features/techdocs/techdocs-faqs" + "features/techdocs/getting-started", + "features/techdocs/concepts", + "features/techdocs/creating-and-publishing", + "features/techdocs/faqs" ] } ], @@ -104,12 +98,51 @@ "conf/writing", "conf/defining" ], - "Authentication and identity": [ + "Auth and identity": [ "auth/index", "auth/add-auth-provider", "auth/auth-backend", "auth/oauth", "auth/glossary" - ] + ], + + "Designing for Backstage": [ + "dls/design", + "dls/contributing-to-storybook", + "dls/figma" + ], + "API references": [ + { + "type": "subcategory", + "label": "TypeScript API", + "ids": [ + "api/utility-apis", + "reference/utility-apis/README", + "reference/createPlugin", + "reference/createPlugin-feature-flags", + "reference/createPlugin-router" + ] + }, + { + "type": "subcategory", + "label": "Backend APIs", + "ids": ["api/backend"] + } + ], + "Tutorials": ["tutorials/index"], + "Architecture Decision Records (ADRs)": [ + "architecture-decisions/adrs-overview", + "architecture-decisions/adrs-adr001", + "architecture-decisions/adrs-adr002", + "architecture-decisions/adrs-adr003", + "architecture-decisions/adrs-adr004", + "architecture-decisions/adrs-adr005", + "architecture-decisions/adrs-adr006", + "architecture-decisions/adrs-adr007", + "architecture-decisions/adrs-adr008" + ], + "Contribute": ["../CONTRIBUTING"], + "Support": ["overview/support"], + "FAQ": ["FAQ"] } } diff --git a/plugins/README.md b/plugins/README.md index a7fe648bf7091..91ad94b8831b2 100644 --- a/plugins/README.md +++ b/plugins/README.md @@ -4,7 +4,7 @@ Backstage is a single-page application composed of a set of plugins. Our goal for the plugin ecosystem is that the definition of a plugin is flexible enough to allow you to expose pretty much any kind of infrastructure or software development tool as a plugin in Backstage. By following strong [design guidelines](https://github.com/spotify/backstage/blob/master/docs/dls/design.md) we ensure the the overall user experience stays consistent between plugins. -![plugin](../docs/plugins/my-plugin_screenshot.png) +![plugin](../docs/assets/my-plugin_screenshot.png) ## Creating a plugin diff --git a/plugins/newrelic/README.md b/plugins/newrelic/README.md index 032d4f035be16..19bd24950cbda 100644 --- a/plugins/newrelic/README.md +++ b/plugins/newrelic/README.md @@ -36,4 +36,4 @@ New Relic Plugin Path: [/newrelic](http://localhost:3000/newrelic) You can also serve the plugin in isolation by running `yarn start` in the plugin directory. This method of serving the plugin provides quicker iteration speed and a faster startup and hot reloads. -It is only meant for local development, and the setup for it can be found inside the [/dev](/dev) directory. +It is only meant for local development, and the setup for it can be found inside the [/dev](./dev) directory.