diff --git a/docs/getting-started/homepage.md b/docs/getting-started/homepage.md index 87cf741b15..b7f7b88c6f 100644 --- a/docs/getting-started/homepage.md +++ b/docs/getting-started/homepage.md @@ -1,30 +1,30 @@ --- id: homepage -title: Backstage Home Page - Setup and Customization +title: Backstage homepage - Setup and Customization description: Documentation on setting up and customizing Backstage homepage --- -## Home Page +## Homepage -Having a good Backstage home page can significantly improve the discoverability of the platform. You want your users to find all the things they need right from the home page and never have to remember direct URLs in Backstage. The [Home plugin](https://github.com/backstage/backstage/tree/master/plugins/home) introduces a system for composing a home page for Backstage in order to surface relevant info and provide convenient shortcuts for common tasks. It's designed with composability in mind with an open ecosystem that allows anyone to contribute with any component, to be included in any home page. +Having a good Backstage homepage can significantly improve the discoverability of the platform. You want your users to find all the things they need right from the homepage and never have to remember direct URLs in Backstage. The [Home plugin](https://github.com/backstage/backstage/tree/master/plugins/home) introduces a system for composing a homepage for Backstage in order to surface relevant info and provide convenient shortcuts for common tasks. It's designed with composability in mind with an open ecosystem that allows anyone to contribute with any component, to be included in any homepage. -For App Integrators, the system is designed to be composable to give total freedom in designing a Home Page that suits the needs of the organization. From the perspective of a Component Developer who wishes to contribute with building blocks to be included in Home Pages, there's a convenient interface for bundling the different parts and exporting them with both error boundary and lazy loading handled under the surface. +For App Integrators, the system is designed to be composable to give total freedom in designing a Homepage that suits the needs of the organization. From the perspective of a Component Developer who wishes to contribute with building blocks to be included in Homepages, there's a convenient interface for bundling the different parts and exporting them with both error boundary and lazy loading handled under the surface. At the end of this tutorial, you can expect: -- Your Backstage app to have a dedicated home page instead of Software Catalog. -- Understand the composability of home page and how to start customizing it for your own organization. +- Your Backstage app to have a dedicated homepage instead of Software Catalog. +- Understand the composability of homepage and how to start customizing it for your own organization. ### Prerequisites Before we begin, make sure - You have created your own standalone Backstage app using [`@backstage/create-app`](index.md#create-your-backstage-app) and not using a fork of the [backstage](https://github.com/backstage/backstage) repository. -- You do not have an existing home page, and by default you are redirected to Software Catalog when you open Backstage. +- 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 home page for your Backstage app. +Now, let's get started by installing the home plugin and creating a simple homepage for your Backstage app. -### Setup home page +### Setup homepage #### 1. Install the plugin @@ -36,20 +36,20 @@ yarn add @backstage/plugin-home #### 2. Create a new HomePage component -Inside your `packages/app` directory, create a new file where our new Home Page component is going to live. Create `packages/app/src/components/home/HomePage.tsx` with the following initial code +Inside your `packages/app` directory, create a new file where our new homepage component is going to live. Create `packages/app/src/components/home/HomePage.tsx` with the following initial code ```tsx import React from 'react'; export const HomePage = () => { - /* We will shortly compose a pretty Home Page here. */ + /* We will shortly compose a pretty homepage here. */ return

Welcome to Backstage!

; }; ``` #### 3. Update router for the root `/` route -If you don't have a home page already, most likely you have a redirect setup to use the Catalog home page as a home page. +If you don't have a homepage already, most likely you have a redirect setup to use the Catalog homepage as a homepage. Inside your `packages/app/src/App.tsx`, look for @@ -59,7 +59,7 @@ const routes = ( ``` -Let's replace the `` line and use the new component we created in the previous step as the new home page. +Let's replace the `` line and use the new component we created in the previous step as the new homepage. ```diff // File: packages/app/src/App.tsx @@ -81,7 +81,7 @@ const routes = ( ### 4. Update sidebar items -Let's update the route for "Home" in the Backstage sidebar to point to the new home page. We'll also add a Sidebar item to quickly open Catalog. +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. @@ -120,7 +120,7 @@ export const Root = ({ children }: PropsWithChildren<{}>) => ( ``` -That's it! You should now have _(although slightly boring)_ a home page! +That's it! You should now have _(although slightly boring)_ a homepage! Screenshot of a blank homepage @@ -128,15 +128,15 @@ In the next steps, we will make it interesting and useful! ### Use the default template -There is a default home page template ([storybook link](https://backstage.io/storybook/?path=/story/plugins-home-templates--default-template)) which we will use to set up our home page. Checkout the [blog post announcement](https://backstage.io/blog/2022/01/25/backstage-homepage-templates) about the Backstage home page templates for more information. +There is a default homepage template ([storybook link](https://backstage.io/storybook/?path=/story/plugins-home-templates--default-template)) which we will use to set up our homepage. Checkout the [blog post announcement](https://backstage.io/blog/2022/01/25/backstage-homepage-templates) about the Backstage homepage templates for more information. -### Composing your Home Page +### Composing your homepage -Composing a Home Page is no different from creating a regular React Component, +Composing a homepage is no different from creating a regular React Component, i.e. the App Integrator is free to include whatever content they like. However, -there are components developed with the Home Page in mind. If you are looking +there are components developed with the homepage in mind. If you are looking for components to use when composing your homepage, you can take a look at the [collection of Homepage components](https://backstage.io/?path=/story/plugins-home-components) in storybook. If you don't find a component that suits your needs but want to