From 21684fe2107e4051b5ded2eb07c4785332026f66 Mon Sep 17 00:00:00 2001 From: Aramis Date: Sat, 10 Feb 2024 11:11:51 -0500 Subject: [PATCH] apply suggestions from code review Signed-off-by: Aramis Signed-off-by: aramissennyeydd --- .../building-plugins-and-modules/01-index.md | 2 +- .../getting-involved.md | 0 .../contributors.md => contribute/index.md} | 4 +-- .../project-structure.md | 0 docs/features/kubernetes/installation.md | 2 +- docs/features/search/getting-started.md | 2 +- docs/features/techdocs/getting-started.md | 2 +- .../building-plugins/01-index.md | 2 +- docs/getting-started/config/database.md | 6 ++--- .../configure-app-with-plugins.md | 4 +-- docs/getting-started/create-a-component.md | 2 +- docs/getting-started/homepage.md | 2 +- .../{standalone-install.md => index.md} | 14 +++++----- docs/getting-started/logging-in.md | 6 +++-- docs/getting-started/register-a-component.md | 2 +- microsite/docusaurus.config.js | 10 +++---- microsite/sidebars.json | 26 ++++++++++++------- mkdocs.yml | 14 +++++----- 18 files changed, 55 insertions(+), 45 deletions(-) rename docs/{getting-started => contribute}/getting-involved.md (100%) rename docs/{getting-started/contributors.md => contribute/index.md} (76%) rename docs/{getting-started => contribute}/project-structure.md (100%) rename docs/getting-started/{standalone-install.md => index.md} (96%) 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 b2f0f09a5c..168646afab 100644 --- a/docs/backend-system/building-plugins-and-modules/01-index.md +++ b/docs/backend-system/building-plugins-and-modules/01-index.md @@ -16,7 +16,7 @@ backend _features_, and are the building blocks that adopters add to their ## Creating a new Plugin -This guide assumes that you already have a Backend project set up. Even if you only want to develop a single plugin for publishing, we still recommend that you do so in a standard Backstage monorepo project, as you often end up needing multiple packages. For instructions on how to set up a new project, see our [getting started](../../getting-started/standalone-install.md#prerequisites) documentation. +This guide assumes that you already have a Backend project set up. Even if you only want to develop a single plugin for publishing, we still recommend that you do so in a standard Backstage monorepo project, as you often end up needing multiple packages. For instructions on how to set up a new project, see our [getting started](../../getting-started/index.md#prerequisites) documentation. To create a Backend plugin, run `yarn new`, select `backend-plugin`, and fill out the rest of the prompts. This will create a new package at `plugins/-backend`, which will be the main entrypoint for your plugin. diff --git a/docs/getting-started/getting-involved.md b/docs/contribute/getting-involved.md similarity index 100% rename from docs/getting-started/getting-involved.md rename to docs/contribute/getting-involved.md diff --git a/docs/getting-started/contributors.md b/docs/contribute/index.md similarity index 76% rename from docs/getting-started/contributors.md rename to docs/contribute/index.md index 9ba338af96..34ed1561cb 100644 --- a/docs/getting-started/contributors.md +++ b/docs/contribute/index.md @@ -1,5 +1,5 @@ --- -id: contributors +id: index title: Contributors # prettier-ignore description: Documentation on how to get set up for doing development on the Backstage repository @@ -11,4 +11,4 @@ Therefore we want to create a strong community of contributors -- all working to Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given. ❤️ -To get you started we've put together a [Contributors Guide in the Backstage GitHub repo](https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md) that has all the information you need. +To get you started, we've put together a [Contributors Guide in the Backstage GitHub repo](https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md) that has all the information you need. diff --git a/docs/getting-started/project-structure.md b/docs/contribute/project-structure.md similarity index 100% rename from docs/getting-started/project-structure.md rename to docs/contribute/project-structure.md diff --git a/docs/features/kubernetes/installation.md b/docs/features/kubernetes/installation.md index f3e46fab68..bdd14098ff 100644 --- a/docs/features/kubernetes/installation.md +++ b/docs/features/kubernetes/installation.md @@ -8,7 +8,7 @@ The Kubernetes feature is a plugin to Backstage, and it is exposed as a tab when viewing entities in the software catalog. If you haven't setup Backstage already, read the -[Getting Started](../../getting-started/standalone-install.md) guide. +[Getting Started](../../getting-started/index.md) guide. ## Adding the Kubernetes frontend plugin diff --git a/docs/features/search/getting-started.md b/docs/features/search/getting-started.md index 599189d192..7989b60ae2 100644 --- a/docs/features/search/getting-started.md +++ b/docs/features/search/getting-started.md @@ -8,7 +8,7 @@ Search functions as a plugin to Backstage, so you will need to use Backstage to use Search. If you haven't setup Backstage already, start -[here](../../getting-started/standalone-install.md). +[here](../../getting-started/index.md). > If you used `npx @backstage/create-app`, and you have a search page defined in > `packages/app/src/components/search`, skip to diff --git a/docs/features/techdocs/getting-started.md b/docs/features/techdocs/getting-started.md index 29419e44f4..eaa6c2de72 100644 --- a/docs/features/techdocs/getting-started.md +++ b/docs/features/techdocs/getting-started.md @@ -8,7 +8,7 @@ TechDocs functions as a plugin to Backstage, so you will need to use Backstage to use TechDocs. If you haven't setup Backstage already, start -[here](../../getting-started/standalone-install.md). +[here](../../getting-started/index.md). > If you used `npx @backstage/create-app`, TechDocs may already be present. > diff --git a/docs/frontend-system/building-plugins/01-index.md b/docs/frontend-system/building-plugins/01-index.md index b6dc6d9308..f8d80f9382 100644 --- a/docs/frontend-system/building-plugins/01-index.md +++ b/docs/frontend-system/building-plugins/01-index.md @@ -14,7 +14,7 @@ frontend _features_, and what you install to build up a Backstage frontend [app] ## Creating a new plugin -This guide assumes that you already have a Backstage project set up. Even if you only want to develop a single plugin for publishing, we still recommend that you do so in a standard Backstage monorepo project, as you often end up needing multiple packages. For instructions on how to set up a new project, see our [getting started](../../getting-started/standalone-install.md#prerequisites) documentation. +This guide assumes that you already have a Backstage project set up. Even if you only want to develop a single plugin for publishing, we still recommend that you do so in a standard Backstage monorepo project, as you often end up needing multiple packages. For instructions on how to set up a new project, see our [getting started](../../getting-started/index.md#prerequisites) documentation. To create a frontend plugin, run `yarn new`, select `plugin`, and fill out the rest of the prompts. This will create a new package at `plugins/`, which will be the main entrypoint for your plugin. diff --git a/docs/getting-started/config/database.md b/docs/getting-started/config/database.md index d836c9aca8..a560fe507b 100644 --- a/docs/getting-started/config/database.md +++ b/docs/getting-started/config/database.md @@ -8,7 +8,7 @@ Audience: Admins ### Summary -This guide walks through how to set up a PostgreSQL database to host your Backstage data. It assumes you've already have a scaffolded Backstage app from following the [Standalone Install](../standalone-install.md) guide. +This guide walks through how to set up a PostgreSQL database to host your Backstage data. It assumes you've already have a scaffolded Backstage app from following the [Standalone Install](../index.md) guide. By the end of this tutorial, you will have a working PostgreSQL database hooked up to your Backstage install. @@ -75,7 +75,7 @@ App. Run the following to install the PostgreSQL client into your backend: ```bash # From your Backstage root directory -yarn add --cwd packages/backend pg +yarn --cwd packages/backend add pg ``` Use your favorite editor to open `app-config.yaml` and add your PostgreSQL @@ -117,7 +117,7 @@ If you opt for the second option of replacing the entire string, take care to no ::: -[Start the Backstage app](../standalone-install.md#2-run-the-backstage-app): +[Start the Backstage app](../index.md#2-run-the-backstage-app): ```shell yarn dev diff --git a/docs/getting-started/configure-app-with-plugins.md b/docs/getting-started/configure-app-with-plugins.md index c8470a8ea0..2fdb016e7b 100644 --- a/docs/getting-started/configure-app-with-plugins.md +++ b/docs/getting-started/configure-app-with-plugins.md @@ -11,7 +11,7 @@ infrastructure needs - CI/CD, monitoring, auditing, and more. ## Adding existing plugins to your app The following steps assume that you have -[created a Backstage app](./standalone-install.md) and want to add an existing plugin +[created a Backstage app](./index.md) and want to add an existing plugin to it. We are using the @@ -75,7 +75,7 @@ to an entity in the software catalog. ### Adding a plugin page to the Sidebar In a standard Backstage app created with -[@backstage/create-app](./standalone-install.md), the sidebar is managed inside +[@backstage/create-app](./index.md), the sidebar is managed inside `packages/app/src/components/Root/Root.tsx`. The file exports the entire `Sidebar` element of your app, which you can extend with additional entries by adding new `SidebarItem` elements. diff --git a/docs/getting-started/create-a-component.md b/docs/getting-started/create-a-component.md index 13d4fb103d..d1718a2739 100644 --- a/docs/getting-started/create-a-component.md +++ b/docs/getting-started/create-a-component.md @@ -18,7 +18,7 @@ If you're running Backstage with Node 20 or later, you'll need to pass the flag ::: -You should already have [a standalone app](./standalone-install.md). +You should already have [a standalone app](./index.md). ## Creating your component diff --git a/docs/getting-started/homepage.md b/docs/getting-started/homepage.md index 4b3eb32b55..7e1a2ed909 100644 --- a/docs/getting-started/homepage.md +++ b/docs/getting-started/homepage.md @@ -19,7 +19,7 @@ At the end of this tutorial, you can expect: Before we begin, make sure -- You have created your own standalone Backstage app using [`@backstage/create-app`](./standalone-install.md#1-create-your-backstage-app) and not using a fork of the [backstage](https://github.com/backstage/backstage) repository. +- You have created your own standalone Backstage app using [`@backstage/create-app`](./index.md#1-create-your-backstage-app) and not using a fork of the [backstage](https://github.com/backstage/backstage) repository. - You do not have an existing homepage, and by default you are redirected to Software Catalog when you open Backstage. Now, let's get started by installing the home plugin and creating a simple homepage for your Backstage app. diff --git a/docs/getting-started/standalone-install.md b/docs/getting-started/index.md similarity index 96% rename from docs/getting-started/standalone-install.md rename to docs/getting-started/index.md index a7b024eb2d..1690035b9b 100644 --- a/docs/getting-started/standalone-install.md +++ b/docs/getting-started/index.md @@ -1,10 +1,11 @@ --- -id: standalone-install -title: Installing a standalone server (Developer or Admin) +id: index +title: Installing a standalone server +sidebar_label: Introduction description: How to install Backstage for your own use. --- -Audience: All +Audience: Developers and Admins ## Summary @@ -154,9 +155,10 @@ Choose the correct next steps for your user role, if you're likely to be deployi ### Developer -- [Logging into Backstage](./logging-in.md) -- [Register a component](./register-a-component.md) -- [Create a new component](./create-a-component.md) +- Using your Backstage instance + - [Logging into Backstage](./logging-in.md) + - [Register a component](./register-a-component.md) + - [Create a new component](./create-a-component.md) Share your experiences, comments, or suggestions with us: [on discord](https://discord.gg/backstage-687207715902193673), file issues for any diff --git a/docs/getting-started/logging-in.md b/docs/getting-started/logging-in.md index cb7de7faef..fef8907e07 100644 --- a/docs/getting-started/logging-in.md +++ b/docs/getting-started/logging-in.md @@ -12,9 +12,9 @@ This guide will provide a quick tutorial on how to log in to your Backstage inst ## Prerequisites -You should have already [have a standalone app](./standalone-install.md) and completed the Github OAuth app setup defined in [the authentication tutorial](./config/authentication.md). +You should have already [have a standalone app](./index.md) and completed the Github OAuth app setup defined in [the authentication tutorial](./config/authentication.md). -## 1. Login to Backstage and check profile +## 1. Login to Backstage Run your Backstage app with `yarn dev`. Navigate to `http://localhost:3000`. @@ -24,6 +24,8 @@ To login, you should choose the "Github" provider and click the "Sign in" button If you are already logged in, you will be automatically brought to your Backstage instance. +## 2. Verify that you're logged in + Once you've logged in, find the "Settings" item in the navigation bar to the left. Click it and you will see your profile. If you see your profile picture and name from Github here, congratulations! You've successfully set up a Github authentication integration. diff --git a/docs/getting-started/register-a-component.md b/docs/getting-started/register-a-component.md index c882c4c05f..c935d25807 100644 --- a/docs/getting-started/register-a-component.md +++ b/docs/getting-started/register-a-component.md @@ -12,7 +12,7 @@ This guide will walk you through how to pull Backstage data from other locations ## Prerequisites -You should have already [have a standalone app](./standalone-install.md). +You should have already [have a standalone app](./index.md). ## 1. Finding our template diff --git a/microsite/docusaurus.config.js b/microsite/docusaurus.config.js index f2da3ea91c..4242bb7150 100644 --- a/microsite/docusaurus.config.js +++ b/microsite/docusaurus.config.js @@ -138,7 +138,7 @@ module.exports = { }, { from: '/docs/getting-started/running-backstage-locally', - to: '/docs/getting-started/standalone-install', + to: '/docs/getting-started/', }, { from: '/docs/features/software-templates/testing-scaffolder-alpha', @@ -154,15 +154,11 @@ module.exports = { }, { from: '/docs/getting-started/create-an-app', - to: '/docs/getting-started/standalone-install', + to: '/docs/getting-started/', }, { from: '/docs/getting-started/configuration', - to: '/docs/getting-started/standalone-install#next-steps', - }, - { - from: '/docs/getting-started', - to: '/docs/getting-started/standalone-install' + to: '/docs/getting-started/#next-steps', }, ], }, diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 5055572ed7..00d70e5583 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -40,10 +40,10 @@ "overview/logos" ], "Getting Started": [ - "getting-started/standalone-install", + "getting-started/index", { "type": "category", - "label": "Configuring Backstage (Admin)", + "label": "Configuring Backstage", "items": [ "getting-started/config/database", "getting-started/config/authentication", @@ -52,14 +52,17 @@ "getting-started/homepage" ] }, - "getting-started/logging-in", - "getting-started/register-a-component", - "getting-started/create-a-component", + { + "type": "category", + "label": "Using Backstage", + "items": [ + "getting-started/logging-in", + "getting-started/register-a-component", + "getting-started/create-a-component" + ] + }, "getting-started/keeping-backstage-updated", - "getting-started/concepts", - "getting-started/contributors", - "getting-started/getting-involved", - "getting-started/project-structure" + "getting-started/concepts" ], "Local Development": [ { @@ -491,6 +494,11 @@ ], "FAQ": ["faq/index", "faq/product", "faq/technical"], "Accessibility": ["accessibility/index"], + "Contribute": [ + "contribute/index", + "contribute/getting-involved", + "contribute/project-structure" + ], "References": ["references/glossary"] } } diff --git a/mkdocs.yml b/mkdocs.yml index b0ac4f0e4c..a0884f5fe1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -20,19 +20,19 @@ nav: - Support and community: 'overview/support.md' - Logo assets: 'overview/logos.md' - Getting Started: - - Installing a standalone server (Developer or Admin): 'getting-started/standalone-install.md' - - Configuring Backstage (Admin): + - Installing a standalone server: 'getting-started/index.md' + - Configuring Backstage: - Database: 'getting-started/config/database.md' - Authentication: 'getting-started/config/authentication.md' - Configuring App with plugins: 'getting-started/configure-app-with-plugins.md' - Customize the look-and-feel of your App: 'getting-started/app-custom-theme.md' - Customizing your Homepage: 'getting-started/homepage.md' - - Logging in: 'getting-started/logging-in.md' - - Register a component: 'getting-started/register-a-component.md' - - Create a component: 'getting-started/create-a-component.md' + - Using Backstage: + - Logging in: 'getting-started/logging-in.md' + - Register a component: 'getting-started/register-a-component.md' + - Create a component: 'getting-started/create-a-component.md' - Keeping Backstage Updated: 'getting-started/keeping-backstage-updated.md' - Key Concepts: 'getting-started/concepts.md' - - Project Structure: 'getting-started/project-structure.md' - Local Development: - CLI: - Overview: 'local-dev/cli-overview.md' @@ -221,5 +221,7 @@ nav: - Overview: 'faq/index.md' - Product FAQ: 'faq/product.md' - Technical FAQ: 'faq/technical.md' + - Contribute: + - Project Structure: 'getting-started/project-structure.md' - References: - Glossary: 'references/glossary.md'