diff --git a/docs/features/kubernetes/installation.md b/docs/features/kubernetes/installation.md index 9e531de655..35a027df62 100644 --- a/docs/features/kubernetes/installation.md +++ b/docs/features/kubernetes/installation.md @@ -7,8 +7,8 @@ description: Installing Kubernetes plugin into Backstage 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, start -[here](../../getting-started/index.md). +If you haven't setup Backstage already, read the +[Getting Started](../../getting-started/index.md). ## Adding the Kubernetes frontend plugin @@ -111,7 +111,7 @@ Backstage app. ## Running Backstage locally Start the frontend and the backend app by -[running backstage locally](../../getting-started/running-backstage-locally.md). +[running Backstage locally](../../getting-started/running-backstage-locally.md). ## Configuration diff --git a/docs/features/search/README.md b/docs/features/search/README.md index 0b13b47979..cd971d9d41 100644 --- a/docs/features/search/README.md +++ b/docs/features/search/README.md @@ -67,7 +67,7 @@ more to come... - As a contributor I should be able to integrate plugin data to the indexing process of Backstage Search by using the standardized API. - As a software engineer I should be able to search for all content (for - example, entities, metadata, documentation) in backstage search. + example, entities, metadata, documentation) in Backstage search. more to come... diff --git a/docs/features/software-templates/extending/create-your-own-templater.md b/docs/features/software-templates/extending/create-your-own-templater.md index 37e68c4153..28769d77e1 100644 --- a/docs/features/software-templates/extending/create-your-own-templater.md +++ b/docs/features/software-templates/extending/create-your-own-templater.md @@ -86,7 +86,7 @@ follows: _note_ Currently the templaters that we provide are basically Docker action containers that are run on top of the skeleton folder. This keeps dependencies -to a minimum for running backstage scaffolder, but you don't _have_ to use +to a minimum for running Backstage scaffolder, but you don't _have_ to use Docker. You can `pip install cookiecutter` to run it locally in your backend. You could create your own templater that spins up an EC2 instance and downloads the folder and does everything using an AMI if you want. It's entirely up to diff --git a/docs/features/software-templates/index.md b/docs/features/software-templates/index.md index 1034ffef0f..898075cb08 100644 --- a/docs/features/software-templates/index.md +++ b/docs/features/software-templates/index.md @@ -39,13 +39,13 @@ internally. ![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 +are required for Backstage usage: the owner (which is a `user` in the backstage system), the `storePath` (which right now must be a GitHub Organisation or GitHub user and a non-existing GitHub repository name in the format `organisation/reponame`), and a GitHub team or user account which should be granted admin access to the repository. -![Enter backstage vars](../../assets/software-templates/template-picked-2.png) +![Enter Backstage vars](../../assets/software-templates/template-picked-2.png) ### Run! diff --git a/docs/features/techdocs/getting-started.md b/docs/features/techdocs/getting-started.md index e1ddfd23f9..5147e17aaa 100644 --- a/docs/features/techdocs/getting-started.md +++ b/docs/features/techdocs/getting-started.md @@ -158,7 +158,7 @@ techdocs: requestUrl: http://localhost:7000/api/techdocs/ ``` -`requestUrl` is used by TechDocs frontend plugin to discover techdocs-backend +`requestUrl` is used by TechDocs frontend plugin to discover `techdocs-backend` endpoints, and the `storageUrl` is another endpoint in `techdocs-backend` which acts as a middleware between TechDocs and the storage (where the static generated docs site are stored). These default values should mostly work for @@ -180,8 +180,8 @@ pipeline, and are being stored in a storage somewhere. When `techdocs.builder` is set to `'external'`, TechDocs becomes more or less a read-only experience where it serves static files from a storage containing all -the generated documentation. Read more in the "Basic" and "Recommended" setup of -TechDocs [here](architecture.md) +the generated documentation. Read more in the "Basic" and "Recommended" sections +of the [TechDocs Architecture](architecture.md). ### Choosing storage (publisher) @@ -190,9 +190,9 @@ fetch the sites from. This is managed by a [Publisher](./concepts.md#techdocs-publisher). Examples: Google Cloud Storage, Amazon S3, or local filesystem of Backstage server. -It is okay to use the local filesystem in a "Basic" setup when you are trying -out Backstage for the first time. Using Cloud Storage is documented -[here](./using-cloud-storage.md). +It is okay to use the local filesystem in a "basic" setup when you are trying +out Backstage for the first time. At a later time, review +[Using Cloud Storage](./using-cloud-storage.md). ```yaml techdocs: @@ -229,23 +229,23 @@ environment is compatible with techdocs. You will have to install the `mkdocs` and `mkdocs-techdocs-core` package from pip, as well as `graphviz` and `plantuml` from your OS package manager (e.g. apt). See our -[Dockerfile](https://github.com/backstage/techdocs-container/blob/main/Dockerfile) -for the latest requirements. You should be trying to match your Dockerfile with -this one. +[`Dockerfile`](https://github.com/backstage/techdocs-container/blob/main/Dockerfile) +for the latest requirements. You should be trying to match your `Dockerfile` +with this one. Note: We recommend Python version 3.7 or higher. -Caveat: Please install the `mkdocs-techdocs-core` package after all other Python -packages. The order is important to make sure we get correct version of some of -the dependencies. For example, we want `Markdown` version to be -[3.2.2](https://github.com/backstage/backstage/blob/f9f70c225548017b6a14daea75b00fbd399c11eb/packages/techdocs-container/techdocs-core/requirements.txt#L11). -You can also explicitly install `Markdown==3.2.2` after installing all other -Python packages. +> Caveat: Please install the `mkdocs-techdocs-core` package after all other +> Python packages. The order is important to make sure we get correct version of +> some of the dependencies. For example, we want `Markdown` version to be +> [3.2.2](https://github.com/backstage/backstage/blob/f9f70c225548017b6a14daea75b00fbd399c11eb/packages/techdocs-container/techdocs-core/requirements.txt#L11). +> You can also explicitly install `Markdown==3.2.2` after installing all other +> Python packages. ## Running Backstage locally Start the frontend and the backend app by -[running backstage locally](../../getting-started/running-backstage-locally.md). +[running Backstage locally](../../getting-started/running-backstage-locally.md). Open your browser at [http://localhost:3000/docs/](http://localhost:3000/docs/) to see all your documentation sites. diff --git a/docs/getting-started/development-environment.md b/docs/getting-started/development-environment.md index b5ff3885b3..01fd7bdc24 100644 --- a/docs/getting-started/development-environment.md +++ b/docs/getting-started/development-environment.md @@ -31,7 +31,7 @@ $ yarn start This should open a local instance of Backstage in your browser, otherwise open one of the URLs printed in the terminal. -By default, backstage will start on port 3000, however you can override this by +By default, Backstage will start on port 3000, however you can override this by setting an environment variable `PORT` on your local machine. e.g. `export PORT=8080` then running `yarn start`. Or `PORT=8080 yarn start`. diff --git a/docs/plugins/create-a-plugin.md b/docs/plugins/create-a-plugin.md index bcb86024fd..4ccd48f17e 100644 --- a/docs/plugins/create-a-plugin.md +++ b/docs/plugins/create-a-plugin.md @@ -9,8 +9,9 @@ A Backstage Plugin adds functionality to Backstage. ## Create a Plugin To create a new plugin, make sure you've run `yarn install` and installed -dependencies, then run the following on your command line (invoking the -`backstage-cli`). +dependencies, then run the following on your command line (a shortcut to +invoking the [`backstage-cli create-plugin`](../cli/commands.md#create-plugin)) +from the root of your project. ```bash yarn create-plugin diff --git a/docs/plugins/integrating-plugin-into-service-catalog.md b/docs/plugins/integrating-plugin-into-service-catalog.md index 51d2331140..01de779635 100644 --- a/docs/plugins/integrating-plugin-into-service-catalog.md +++ b/docs/plugins/integrating-plugin-into-service-catalog.md @@ -59,7 +59,7 @@ accordingly inside `Router.tsx`) ### Import and use router in the APP In the `app/src/components/catalog/EntityPage.tsx` (app === your folder, -containing backstage app) import your created Router: +containing Backstage app) import your created Router: ```tsx import { Router as MyPluginRouter } from '@backstage/plugin-my-plugin; diff --git a/docs/reference/utility-apis/BackstageIdentityApi.md b/docs/reference/utility-apis/BackstageIdentityApi.md index dafdb7d55f..69fe5d26ba 100644 --- a/docs/reference/utility-apis/BackstageIdentityApi.md +++ b/docs/reference/utility-apis/BackstageIdentityApi.md @@ -79,7 +79,7 @@ Referenced by: [getBackstageIdentity](#getbackstageidentity).
 export type BackstageIdentity = {
   /**
-   * The backstage user ID.
+   * The Backstage user ID.
    */
   id: string;