From 7a23cdfa59a5b864139ad2cdfef7824bdb48d36f Mon Sep 17 00:00:00 2001 From: Johan Haals Date: Tue, 21 Feb 2023 11:43:14 +0100 Subject: [PATCH 1/4] Update image links to use markdown syntax MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Ben Lambert Co-authored-by: Fredrik Adelöw Signed-off-by: Johan Haals --- docs/api/utility-apis.md | 4 +-- .../building-plugins-and-modules/01-index.md | 2 +- docs/features/search/architecture.md | 4 ++- docs/features/techdocs/addons.md | 4 ++- docs/features/techdocs/architecture.md | 8 +++-- docs/features/techdocs/getting-started.md | 8 +++-- docs/getting-started/configuration.md | 35 +++++++------------ docs/getting-started/create-an-app.md | 4 +-- docs/getting-started/homepage.md | 17 ++++----- docs/getting-started/index.md | 12 ++----- 10 files changed, 43 insertions(+), 55 deletions(-) diff --git a/docs/api/utility-apis.md b/docs/api/utility-apis.md index a69c874307..44c00d1ab7 100644 --- a/docs/api/utility-apis.md +++ b/docs/api/utility-apis.md @@ -290,9 +290,7 @@ The figure below shows the relationship between FooApi via the 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](../assets/utility-apis-fig1.svg) The current method for connecting Utility API providers and consumers is via the React tree using an `ApiProvider`, which is added to the `AppProvider` of the diff --git a/docs/backend-system/building-plugins-and-modules/01-index.md b/docs/backend-system/building-plugins-and-modules/01-index.md index 18cbabfe5d..848a38ce16 100644 --- a/docs/backend-system/building-plugins-and-modules/01-index.md +++ b/docs/backend-system/building-plugins-and-modules/01-index.md @@ -74,7 +74,7 @@ Backend modules are used to extend [plugins](../architecture/04-plugins.md) with additional features or change existing behavior. They must always be installed in the same backend instance as the plugin that they extend, and may only extend a single plugin. Modules interact with their target plugin using the [extension -points](./05-extension-points.md) registered by the plugin, while also being +points](../architecture/05-extension-points.md) registered by the plugin, while also being able to depend on the [services](../architecture/03-services.md) of that plugin. That last point is worth reiterating: injected `plugin` scoped services will be the exact diff --git a/docs/features/search/architecture.md b/docs/features/search/architecture.md index f1183cec5f..62f3a68ff6 100644 --- a/docs/features/search/architecture.md +++ b/docs/features/search/architecture.md @@ -9,7 +9,9 @@ to support a wide variety of search engines, while providing a simple developer experience for plugin developers, and a good out-of-the-box experience for Backstage end-users. -Search Architecture + + +![Search Architecture](../../assets/search/architecture.drawio.svg) At a base-level, we want to support the following: diff --git a/docs/features/techdocs/addons.md b/docs/features/techdocs/addons.md index 60999f599c..bd709ee15f 100644 --- a/docs/features/techdocs/addons.md +++ b/docs/features/techdocs/addons.md @@ -39,7 +39,9 @@ representative of physical spaces in the TechDocs UI: - `Component`: A [proposed-but-not-yet-implemented](https://github.com/backstage/backstage/issues/11109) virtual location, aimed at simplifying a common type of Addon. -TechDocs Addon Location Guide + + +![TechDocs Addon Location Guide](../../assets/techdocs/addon-locations.png) ### Addon Registry diff --git a/docs/features/techdocs/architecture.md b/docs/features/techdocs/architecture.md index d781f71917..2cb8543ccd 100644 --- a/docs/features/techdocs/architecture.md +++ b/docs/features/techdocs/architecture.md @@ -9,7 +9,9 @@ description: Documentation on TechDocs Architecture When you deploy Backstage (with TechDocs enabled by default), you get a basic out-of-the box experience. -TechDocs Architecture diagram + + +![TechDocs Architecture diagram](../../assets/techdocs/architecture-basic.drawio.svg) > Note: See below for our recommended deployment architecture which takes care > of stability, scalability and speed. Also look at the @@ -42,7 +44,9 @@ storage system (e.g. AWS S3, GCS or Azure Blob Storage). Read more in This is how we recommend deploying TechDocs in a production environment. -TechDocs Architecture diagram + + +![TechDocs Architecture diagram](../../assets/techdocs/architecture-recommended.drawio.svg) The key difference in the recommended deployment approach is where the docs are built. diff --git a/docs/features/techdocs/getting-started.md b/docs/features/techdocs/getting-started.md index 578a631798..3f7edd23a0 100644 --- a/docs/features/techdocs/getting-started.md +++ b/docs/features/techdocs/getting-started.md @@ -89,11 +89,15 @@ const AppRoutes = () => { I know, you're curious to see how it looks, aren't you? See the image below: -TechDocs Report Issue Add-on + + +![TechDocs Report Issue Add-on](../../assets/techdocs/report-issue-addon.png) By clicking the open new issue button, you will be redirected to the new issue page according to the source code provider you are using: -TechDocs Report Issue Template + + +![TechDocs Report Issue Template](../../assets/techdocs/report-issue-template.png) That's it! Now, we need the TechDocs Backend plugin for the frontend to work. diff --git a/docs/getting-started/configuration.md b/docs/getting-started/configuration.md index 0441d3f589..1c25606ac3 100644 --- a/docs/getting-started/configuration.md +++ b/docs/getting-started/configuration.md @@ -136,9 +136,7 @@ frontend, in our tutorial it would be `http://localhost:3000`. The `Authorization callback URL` will point to the auth backend, which will most likely be `http://localhost:7007/api/auth/github/handler/frame`. -

- Screenshot of the GitHub OAuth creation page -

+![Screenshot of the GitHub OAuth creation page](../assets/getting-started/gh-oauth.png) Take note of the `Client ID` and the `Client Secret`. Open `app-config.yaml`, and add your `clientId` and `clientSecret` to this file. It should end up @@ -214,9 +212,7 @@ name to identify this token and put it in the notes field. Choose a number of days for expiration. If you have a hard time picking a number, we suggest to go for 7 days, it's a lucky number. -

- Screenshot of the GitHub Personal Access Token creation page -

+![Screenshot of the GitHub Personal Access Token creation page](../assets/getting-started/gh-pat.png) Set the scope to your likings. For this tutorial, selecting `repo` and `workflow` is required as the scaffolding job in this guide configures a GitHub actions workflow for the newly created project. @@ -262,21 +258,18 @@ otherwise something went terribly wrong. - Register a new component, by going to `create` and choose `Register existing component` -

- Software template main screen, with a blue button to add an existing component -

+ + + ![Software template main screen, with a blue button to add an existing component](../assets/getting-started/b-existing-1.png) - As URL use `https://github.com/backstage/demo/blob/master/catalog-info.yaml`. This is used by our [demo site](https://demo.backstage.io). -

- Register a new component wizard, asking for an URL to the existing component YAML file -

-- Hit `Analyze` and review the changes. Apply them if correct + ![Register a new component wizard, asking for an URL to the existing component YAML file](../assets/getting-started/b-existing-2.png) -

- Register a new component wizard, showing the metadata for the component YAML we use in this tutorial -

+- Hit `Analyze` and review the changes. Apply them if correct. + + ![Register a new component wizard, showing the metadata for the component YAML we use in this tutorial](../assets/getting-started/b-existing-3.png) - You should receive a message that your entities have been added. - If you go back to `Home`, you should be able to find `demo`. You should be @@ -286,14 +279,12 @@ otherwise something went terribly wrong. - Go to `create` and choose to create a website with the `Example Node.js Template` - Type in a name, let's use `tutorial` and click `Next Step` -

- Software template deployment input screen asking for a name -

+ +![Software template deployment input screen asking for a name](../assets/getting-started/b-scaffold-1.png) - You should see the following screen: -

- Software template deployment input screen asking for the GitHub username, and name of the new repo to create -

+ +![Software template deployment input screen asking for the GitHub username, and name of the new repo to create](../assets/getting-started/b-scaffold-2.png) - For host, it should default to github.com - As owner, type your GitHub username diff --git a/docs/getting-started/create-an-app.md b/docs/getting-started/create-an-app.md index 05c12ffb75..535bc848fc 100644 --- a/docs/getting-started/create-an-app.md +++ b/docs/getting-started/create-an-app.md @@ -34,9 +34,7 @@ npx @backstage/create-app This will create a new Backstage App inside the current folder. The name of the app-folder is the name that was provided when prompted. -

- create app -

+![create app](../assets/getting-started/create-app_output.png) Inside that directory, it will generate all the files and folder structure needed for you to run your app. diff --git a/docs/getting-started/homepage.md b/docs/getting-started/homepage.md index 7db41d7768..9fa91e694f 100644 --- a/docs/getting-started/homepage.md +++ b/docs/getting-started/homepage.md @@ -82,16 +82,9 @@ const routes = ( Let's update the route for "Home" in the Backstage sidebar to point to the new homepage. We'll also add a Sidebar item to quickly open Catalog. - - - - - - - - - -
Sidebar without CatalogSidebar with Catalog
BeforeAfter
+| Before | After | +| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | +| ![Sidebar without Catalog](../assets/getting-started/sidebar-without-catalog.png) | ![Sidebar with Catalog](../assets/getting-started/sidebar-with-catalog.png) | The code for the Backstage sidebar is most likely inside your [`packages/app/src/components/Root/Root.tsx`](https://github.com/backstage/backstage/blob/master/packages/app/src/components/Root/Root.tsx). @@ -121,7 +114,9 @@ export const Root = ({ children }: PropsWithChildren<{}>) => ( That's it! You should now have _(although slightly boring)_ a homepage! -Screenshot of a blank homepage + + +![Screenshot of a blank homepage](../assets/getting-started/simple-homepage.png) In the next steps, we will make it interesting and useful! diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 962919015b..c3d6b21923 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -54,9 +54,7 @@ npx @backstage/create-app@latest The wizard will ask you for the name of the app, which will also be the name of the directory -

- Screenshot of the wizard asking for a name for the app. -

+![Screenshot of the wizard asking for a name for the app.](../assets/getting-started/wizard.png) ### Run the Backstage app @@ -69,9 +67,7 @@ cd my-backstage-app yarn dev ``` -

- Screenshot of the command output, with the message web pack compiled successfully. -

+![Screenshot of the command output, with the message web pack compiled successfully](../assets/getting-started/startup.png) It might take a little while, but as soon as the message `[0] webpack compiled successfully` appears, you can open a browser and directly @@ -80,9 +76,7 @@ You can start exploring the demo immediately. Please note that the in-memory database will be cleared when you restart the app, so you'll most likely want to carry on with the database steps. -

- Screenshot of the Backstage portal. -

+![Screenshot of the Backstage portal.](../assets/getting-started/portal.png) In the next part of this tutorial, you'll learn how to change to a persistent database, configure authentication, and add your first integration. Continue From 4975e751f1aedea4f29209a2ccbe098d5902bf73 Mon Sep 17 00:00:00 2001 From: Johan Haals Date: Tue, 21 Feb 2023 11:43:55 +0100 Subject: [PATCH 2/4] Update sidebar Signed-off-by: Johan Haals --- microsite-next/sidebars.json | 52 ++++++++++++++++++++++++++++++++---- 1 file changed, 47 insertions(+), 5 deletions(-) diff --git a/microsite-next/sidebars.json b/microsite-next/sidebars.json index 67c4209976..f489771fa0 100644 --- a/microsite-next/sidebars.json +++ b/microsite-next/sidebars.json @@ -1,6 +1,9 @@ { "releases": { "Release Notes": [ + "releases/v1.11.0", + "releases/v1.10.0", + "releases/v1.9.0", "releases/v1.8.0", "releases/v1.7.0", "releases/v1.6.0", @@ -85,7 +88,8 @@ "features/kubernetes/installation", "features/kubernetes/configuration", "features/kubernetes/authentication", - "features/kubernetes/troubleshooting" + "features/kubernetes/troubleshooting", + "features/kubernetes/proxy" ] }, { @@ -101,6 +105,7 @@ "features/software-templates/writing-custom-actions", "features/software-templates/writing-custom-field-extensions", "features/software-templates/writing-custom-step-layouts", + "features/software-templates/testing-scaffolder-alpha", "features/software-templates/migrating-from-v1beta2-to-v1beta3" ] }, @@ -199,7 +204,8 @@ "label": "GitLab", "items": [ "integrations/gitlab/locations", - "integrations/gitlab/discovery" + "integrations/gitlab/discovery", + "integrations/gitlab/org" ] }, { @@ -237,8 +243,7 @@ "plugins/proxying", "plugins/backend-plugin", "plugins/call-existing-api", - "plugins/url-reader", - "plugins/new-backend-system" + "plugins/url-reader" ] }, { @@ -361,6 +366,43 @@ "architecture-decisions/adrs-adr012", "architecture-decisions/adrs-adr013" ], - "FAQ": ["FAQ"] + "FAQ": ["FAQ"], + "Experimental Backend System": [ + "backend-system/index", + { + "type": "category", + "label": "Architecture", + "items": [ + "backend-system/architecture/index", + "backend-system/architecture/services", + "backend-system/architecture/plugins", + "backend-system/architecture/extension-points", + "backend-system/architecture/modules", + "backend-system/architecture/naming-patterns" + ] + }, + { + "type": "category", + "label": "Building Backends", + "items": [ + "backend-system/building-backends/index", + "backend-system/building-backends/migrating" + ] + }, + { + "type": "category", + "label": "Building Plugins & Modules", + "items": [ + "backend-system/building-plugins-and-modules/index", + "backend-system/building-plugins-and-modules/testing", + "backend-system/building-plugins-and-modules/migrating" + ] + }, + { + "type": "category", + "label": "Core Services", + "items": ["backend-system/core-services/index"] + } + ] } } From 185abd171d1d8318509f4f888cb070bb3ca04c34 Mon Sep 17 00:00:00 2001 From: Johan Haals Date: Tue, 21 Feb 2023 11:44:09 +0100 Subject: [PATCH 3/4] Use new search index configuration Signed-off-by: Johan Haals --- microsite-next/docusaurus.config.js | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/microsite-next/docusaurus.config.js b/microsite-next/docusaurus.config.js index 52867ed121..b050f4d914 100644 --- a/microsite-next/docusaurus.config.js +++ b/microsite-next/docusaurus.config.js @@ -218,9 +218,9 @@ module.exports = { '

Made with ❤️ at Spotify

Copyright © 2022 Backstage Project Authors. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Usage page: https://www.linuxfoundation.org/trademark-usage

', }, algolia: { - appId: 'AZYC4ZFNTN', - apiKey: '7dbd2089b0d445ee0d87db71abfc794f', - indexName: 'backstage', + apiKey: '10b9e6c92a4513c1cf390f50e53aad1f', + indexName: 'backstage_io', + appId: 'JCMFNHCHI8', searchParameters: {}, }, }, From b2ac4ebb9431c943e652a24c3554428281d2503c Mon Sep 17 00:00:00 2001 From: Johan Haals Date: Tue, 21 Feb 2023 13:45:37 +0100 Subject: [PATCH 4/4] Update search index Signed-off-by: Johan Haals --- microsite-next/docusaurus.config.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/microsite-next/docusaurus.config.js b/microsite-next/docusaurus.config.js index b050f4d914..a5dbd144da 100644 --- a/microsite-next/docusaurus.config.js +++ b/microsite-next/docusaurus.config.js @@ -218,8 +218,8 @@ module.exports = { '

Made with ❤️ at Spotify

Copyright © 2022 Backstage Project Authors. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Usage page: https://www.linuxfoundation.org/trademark-usage

', }, algolia: { - apiKey: '10b9e6c92a4513c1cf390f50e53aad1f', - indexName: 'backstage_io', + apiKey: '1f0ba86672ccfc3576faa94583e5b318', + indexName: 'crawler_Backstage Docusaurus 2', appId: 'JCMFNHCHI8', searchParameters: {}, },