paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 28 Packages Projects Releases Wiki Activity

Add titles to codeblocks and switch from diff codeblock to language codeblock

Browse Source 
Signed-off-by: Paul Schultz <pschultz@pobox.com>
This commit is contained in:
Paul Schultz
2023-03-01 13:30:38 -06:00
parent adf9fe58f5
commit 9c95f91c0a
44 changed files with 2257 additions and 1869 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/getting-started/app-custom-theme.md
+90 -90
View File
@@ -172,7 +172,7 @@ When creating a custom theme you would be applying different values to
component's css rules that use the theme object. For example, a Backstage
component's styles might look like this:
```ts
```tsx
const useStyles = makeStyles<BackstageTheme>(
theme => ({
header: {
@@ -263,11 +263,9 @@ You can also use another web image format such as PNG by importing it. To do
this, place your new image into a new subdirectory such as
`src/components/Root/logo/my-company-logo.png`, and then add this code:
```jsx
```tsx
import MyCustomLogoFull from './logo/my-company-logo.png';
//...
const LogoFull = () => {
return <img src={MyCustomLogoFull} />;
};
@@ -294,8 +292,7 @@ In your front-end application, locate the `src` folder. We suggest creating the
> Another example [here](https://github.com/backstage/backstage/blob/master/plugins/azure-devops/src/components/AzurePipelinesIcon/AzurePipelinesIcon.tsx), if you want to ensure proper behavior in light and dark themes.
```tsx
// customIcons.tsx
```tsx title="customIcons.tsx"
import { SvgIcon, SvgIconProps } from '@material-ui/core';
import React from 'react';
@@ -317,29 +314,28 @@ export const ExampleIcon = (props: SvgIconProps) => (
Supply your custom icon in `packages/app/src/App.tsx`
```diff
```tsx title="packages/app/src/App.tsx"
/* highlight-add-next-line */
import { ExampleIcon } from './assets/customIcons'
+ import { ExampleIcon } from './assets/customIcons'
[...]
const app = createApp({
apis,
components: {
[...]
{/* ... */}
},
themes: [
[...]
{/* ... */}
],
+ icons: {
+ github: ExampleIcon,
+ },
/* highlight-add-start */
icons: {
github: ExampleIcon,
},
/* highlight-add-end */
bindRoutes({ bind }) {
[...]
{/* ... */}
}
})
[...]
```
### Adding Icons
@@ -350,17 +346,19 @@ You can add more icons, if the [default icons](https://github.com/backstage/back
2. Then you want to import your icon, add this to the rest of your imports: `import AlarmIcon from '@material-ui/icons/Alarm';`
3. Next you want to add the icon like this to your `createApp`:
```diff
const app = createApp({
apis: ...,
plugins: ...,
+ icons: {
+ alert: AlarmIcon,
+ },
themes: ...,
components: ...,
});
```
```tsx title="packages/app/src/App.tsx"
const app = createApp({
apis: ...,
plugins: ...,
/* highlight-add-start */
icons: {
alert: AlarmIcon,
},
/* highlight-add-end */
themes: ...,
components: ...,
});
```
4. Now we can reference `alert` for our icon in our entity links like this:
@@ -404,7 +402,7 @@ For this example we'll show you how you can expand the sidebar with a sub-menu:
1. Open the `Root.tsx` file located in `packages/app/src/components/Root` as this is where the sidebar code lives
2. Then we want to add the following imports for the icons:
```ts
```tsx title="packages/app/src/components/Root/Root.tsx"
import ApiIcon from '@material-ui/icons/Extension';
import ComponentIcon from '@material-ui/icons/Memory';
import DomainIcon from '@material-ui/icons/Apartment';
@@ -415,69 +413,71 @@ For this example we'll show you how you can expand the sidebar with a sub-menu:
3. Then update the `@backstage/core-components` import like this:
```diff
import {
Sidebar,
sidebarConfig,
SidebarDivider,
SidebarGroup,
SidebarItem,
SidebarPage,
SidebarScrollWrapper,
SidebarSpace,
useSidebarOpenState,
Link,
+ GroupIcon,
+ SidebarSubmenu,
+ SidebarSubmenuItem,
} from '@backstage/core-components';
```
```tsx
import {
Sidebar,
sidebarConfig,
SidebarDivider,
SidebarGroup,
SidebarItem,
SidebarPage,
SidebarScrollWrapper,
SidebarSpace,
useSidebarOpenState,
Link,
/* highlight-add-start */
GroupIcon,
SidebarSubmenu,
SidebarSubmenuItem,
/* highlight-add-end */
} from '@backstage/core-components';
```
4. Finally replace `<SidebarItem icon={HomeIcon} to="catalog" text="Home" />` with this:
```ts
<SidebarItem icon={HomeIcon} to="catalog" text="Home">
<SidebarSubmenu title="Catalog">
<SidebarSubmenuItem
title="Domains"
to="catalog?filters[kind]=domain"
icon={DomainIcon}
/>
<SidebarSubmenuItem
title="Systems"
to="catalog?filters[kind]=system"
icon={SystemIcon}
/>
<SidebarSubmenuItem
title="Components"
to="catalog?filters[kind]=component"
icon={ComponentIcon}
/>
<SidebarSubmenuItem
title="APIs"
to="catalog?filters[kind]=api"
icon={ApiIcon}
/>
<SidebarDivider />
<SidebarSubmenuItem
title="Resources"
to="catalog?filters[kind]=resource"
icon={ResourceIcon}
/>
<SidebarDivider />
<SidebarSubmenuItem
title="Groups"
to="catalog?filters[kind]=group"
icon={GroupIcon}
/>
<SidebarSubmenuItem
title="Users"
to="catalog?filters[kind]=user"
icon={UserIcon}
/>
</SidebarSubmenu>
</SidebarItem>
```
```tsx
<SidebarItem icon={HomeIcon} to="catalog" text="Home">
<SidebarSubmenu title="Catalog">
<SidebarSubmenuItem
title="Domains"
to="catalog?filters[kind]=domain"
icon={DomainIcon}
/>
<SidebarSubmenuItem
title="Systems"
to="catalog?filters[kind]=system"
icon={SystemIcon}
/>
<SidebarSubmenuItem
title="Components"
to="catalog?filters[kind]=component"
icon={ComponentIcon}
/>
<SidebarSubmenuItem
title="APIs"
to="catalog?filters[kind]=api"
icon={ApiIcon}
/>
<SidebarDivider />
<SidebarSubmenuItem
title="Resources"
to="catalog?filters[kind]=resource"
icon={ResourceIcon}
/>
<SidebarDivider />
<SidebarSubmenuItem
title="Groups"
to="catalog?filters[kind]=group"
icon={GroupIcon}
/>
<SidebarSubmenuItem
title="Users"
to="catalog?filters[kind]=user"
icon={UserIcon}
/>
</SidebarSubmenu>
</SidebarItem>
```
When you startup your Backstage app and hover over the Home option on the sidebar you'll now see a nice sub-menu appear with links to the various Kinds in your Catalog. It would look like this:
docs/getting-started/configuration.md
+23 -19
View File
@@ -74,22 +74,26 @@ Use your favorite editor to open `app-config.yaml` and add your PostgreSQL
configuration. in the root directory of your Backstage app using the credentials
from the previous steps.
```diff
```yaml title="app-config.yaml"
backend:
database:
- client: better-sqlite3
- connection: ':memory:'
+ # config options: https://node-postgres.com/apis/client
+ client: pg
+ connection:
+ host: ${POSTGRES_HOST}
+ port: ${POSTGRES_PORT}
+ user: ${POSTGRES_USER}
+ password: ${POSTGRES_PASSWORD}
+ # https://node-postgres.com/features/ssl
+ #ssl: require # see https://www.postgresql.org/docs/current/libpq-ssl.html Table 33.1. SSL Mode Descriptions (e.g. require)
+ #ca: # if you have a CA file and want to verify it you can uncomment this section
+ #$file: <file-path>/ca/server.crt
# highlight-remove-start
client: better-sqlite3
connection: ':memory:'
# highlight-remove-end
# highlight-add-start
# config options: https://node-postgres.com/apis/client
client: pg
connection:
host: ${POSTGRES_HOST}
port: ${POSTGRES_PORT}
user: ${POSTGRES_USER}
password: ${POSTGRES_PASSWORD}
# https://node-postgres.com/features/ssl
# ssl: require # see https://www.postgresql.org/docs/current/libpq-ssl.html Table 33.1. SSL Mode Descriptions (e.g. require)
#ca: # if you have a CA file and want to verify it you can uncomment this section
#$file: <file-path>/ca/server.crt
# highlight-add-end
```
You'll use the connection details from the previous step. You can either set the
@@ -142,7 +146,7 @@ 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
looking like this:
```yaml
```yaml title="app-config.yaml"
auth:
# see https://backstage.io/docs/auth/ to learn about auth providers
environment: development
@@ -161,14 +165,14 @@ change the sign-in page, this you actually need to add in the source code.
Open `packages/app/src/App.tsx` and below the last `import` line, add:
```typescript
```typescript title="packages/app/src/App.tsx"
import { githubAuthApiRef } from '@backstage/core-plugin-api';
import { SignInPage } from '@backstage/core-components';
```
Search for `const app = createApp({` in this file, and below `apis,` add:
```typescript
```tsx title="packages/app/src/App.tsx"
components: {
SignInPage: props => (
<SignInPage
@@ -221,7 +225,7 @@ This file should also be excluded in `.gitignore`, to avoid accidental committin
In your `app-config.local.yaml` go ahead and add the following:
```yaml
```yaml title="app-config.local.yaml"
integrations:
github:
- host: github.com
@@ -232,7 +236,7 @@ That's settled. This information will be leveraged by other plugins.
If you're looking for a more production way to manage this secret, then you can do the following with the token being stored in an environment variable called `GITHUB_TOKEN`.
```yaml
```yaml title="app-config.local.yaml"
integrations:
github:
- host: github.com
docs/getting-started/configure-app-with-plugins.md
+23 -22
View File
@@ -33,23 +33,25 @@ to an entity in the software catalog.
2. Add the `EntityCircleCIContent` extension to the entity pages in the app:
```diff
// packages/app/src/components/catalog/EntityPage.tsx
+import {
+ EntityCircleCIContent,
+ isCircleCIAvailable,
+} from '@backstage/plugin-circleci';
```tsx title="packages/app/src/components/catalog/EntityPage.tsx"
/* highlight-add-start */
import {
EntityCircleCIContent,
isCircleCIAvailable,
} from '@backstage/plugin-circleci';
/* highlight-add-end */
...
const cicdContent = (
<EntitySwitch>
...
+ <EntitySwitch.Case if={isCircleCIAvailable}>
+ <EntityCircleCIContent />
+ </EntitySwitch.Case>;
</EntitySwitch>
);
```
const cicdContent = (
<EntitySwitch>
{/* ... */}
{/* highlight-add-next-line */}
<EntitySwitch.Case if={isCircleCIAvailable}>
<EntityCircleCIContent />
</EntitySwitch.Case>;
{/* highlight-add-end */}
</EntitySwitch>
);
```
This is just one example, but each Backstage instance may integrate content or
cards to suit their needs on different pages, tabs, etc. In addition, while some
@@ -62,8 +64,7 @@ to an entity in the software catalog.
Plugins that collect data off of external services may require the use of a proxy service.
This plugin accesses the CircleCI REST API, and thus requires a proxy definition.
```yaml
// app-config.yaml
```yaml title="app-config.yaml"
proxy:
'/circleci/api':
target: https://circleci.com/api/v1.1
@@ -82,7 +83,7 @@ adding new `SidebarItem` elements.
For example, if you install the `api-docs` plugin, a matching `SidebarItem`
could be something like this:
```tsx
```tsx title="packages/app/src/components/Root/Root.tsx"
// Import icon from MUI
import ExtensionIcon from '@material-ui/icons/Extension';
@@ -95,7 +96,7 @@ are sized according to the Material UI's
[SvgIcon](https://material-ui.com/api/svg-icon/) default of 24x24px, and set the
extension to `.icon.svg`. For example:
```ts
```tsx
import InternalToolIcon from './internal-tool.icon.svg';
```
@@ -104,7 +105,7 @@ customizing the experience you can group `SidebarItems` in a `SidebarGroup`
(Example 1) or create a `SidebarGroup` with a link (Example 2). All
`SidebarGroup`s are displayed in the bottom navigation with an icon.
```ts
```tsx
// Example 1
<SidebarGroup icon={<MenuIcon />} label="Menu">
...
@@ -113,7 +114,7 @@ customizing the experience you can group `SidebarItems` in a `SidebarGroup`
<SidebarGroup />
```
```ts
```tsx
// Example 2
<SidebarGroup label="Search" icon={<SearchIcon />} to="/search">
...
docs/getting-started/homepage.md
+33 -20
View File
@@ -52,29 +52,34 @@ If you don't have a homepage already, most likely you have a redirect setup to u
Inside your `packages/app/src/App.tsx`, look for
```tsx
```tsx title="packages/app/src/App.tsx"
const routes = (
<FlatRoutes>
<Navigate key="/" to="catalog" />
{/* ... */}
</FlatRoutes>
)
```
Let's replace the `<Navigate>` line and use the new component we created in the previous step as the new homepage.
```diff
// File: packages/app/src/App.tsx
```tsx title="packages/app/src/App.tsx"
/* highlight-add-start */
import { HomepageCompositionRoot } from '@backstage/plugin-home';
import { HomePage } from './components/home/HomePage';
/* highlight-add-end */
+ import { HomepageCompositionRoot } from '@backstage/plugin-home';
+ import { HomePage } from './components/home/HomePage';
// ...
const routes = (
<FlatRoutes>
- <Navigate key="/" to="catalog" />
+ <Route path="/" element={<HomepageCompositionRoot />}>
+ <HomePage />
+ </Route>
// ...
{/* highlight-remove-next-line */}
<Navigate key="/" to="catalog" />
{/* highlight-add-start */}
<Route path="/" element={<HomepageCompositionRoot />}>
<HomePage />
</Route>
{/* highlight-add-end */}
{/* ... */}
</FlatRoutes>
)
```
@@ -90,26 +95,34 @@ The code for the Backstage sidebar is most likely inside your [`packages/app/src
Let's make the following changes
```diff
// Other imports
+ import CategoryIcon from '@material-ui/icons/Category';
```tsx title="packages/app/src/components/Root/Root.tsx"
/* highlight-add-next-line */
import CategoryIcon from '@material-ui/icons/Category';
export const Root = ({ children }: PropsWithChildren<{}>) => (
<SidebarPage>
<Sidebar>
<SidebarLogo />
# ...
{/* ... */}
<SidebarGroup label="Menu" icon={<MenuIcon />}>
{/* Global nav, not org-specific */}
- <SidebarItem icon={HomeIcon} to="catalog" text="Home" />
+ <SidebarItem icon={HomeIcon} to="/" text="Home" />
+ <SidebarItem icon={CategoryIcon} to="catalog" text="Catalog" />
{/* highlight-remove-next-line */}
<SidebarItem icon={HomeIcon} to="catalog" text="Home" />
{/* highlight-add-start */}
<SidebarItem icon={HomeIcon} to="/" text="Home" />
<SidebarItem icon={CategoryIcon} to="catalog" text="Catalog" />
{/* highlight-add-end */}
<SidebarItem icon={ExtensionIcon} to="api-docs" text="APIs" />
<SidebarItem icon={LibraryBooks} to="docs" text="Docs" />
<SidebarItem icon={LayersIcon} to="explore" text="Explore" />
<SidebarItem icon={CreateComponentIcon} to="create" text="Create..." />
{/* End global nav */}
<SidebarDivider />
{/* ... */}
</SidebarGroup>
</Sidebar>
</SidebarPage>
)
```
That's it! You should now have _(although slightly boring)_ a homepage!