diff --git a/docs/features/kubernetes/installation.md b/docs/features/kubernetes/installation.md index 42ceaaa016..b3d03cc0b4 100644 --- a/docs/features/kubernetes/installation.md +++ b/docs/features/kubernetes/installation.md @@ -236,7 +236,11 @@ backend.add(kubernetesModuleCustomClusterDiscovery); backend.start(); ``` -> Note: this example assumes the `CustomClustersSupplier` class is the same from the [previous example](#custom-cluster-discovery) +:::note Note + +This example assumes the `CustomClustersSupplier` class is the same from the [previous example](#custom-cluster-discovery) + +::: ## Configuration diff --git a/docs/features/search/search-engines.md b/docs/features/search/search-engines.md index d06e401847..86b6244fb6 100644 --- a/docs/features/search/search-engines.md +++ b/docs/features/search/search-engines.md @@ -34,10 +34,14 @@ const searchEngine = new LunrSearchEngine({ logger: env.logger }); const indexBuilder = new IndexBuilder({ logger: env.logger, searchEngine }); ``` -> Note: Lunr is appropriate as a zero-config search engine when developing -> other parts of Backstage locally, however its use is highly discouraged when -> running Backstage in production. When deploying Backstage, use one of the -> other search engines instead. +:::note Note + +Lunr is appropriate as a zero-config search engine when developing +other parts of Backstage locally, however its use is highly discouraged when +running Backstage in production. When deploying Backstage, use one of the +other search engines instead. + +::: ## Postgres diff --git a/docs/features/software-catalog/catalog-customization.md b/docs/features/software-catalog/catalog-customization.md index 3dc47a610a..0c8eb7bcda 100644 --- a/docs/features/software-catalog/catalog-customization.md +++ b/docs/features/software-catalog/catalog-customization.md @@ -95,7 +95,11 @@ const myColumnsFunc: CatalogTableColumnsFunc = entityListContext => { } /> ``` -> Note: the above example has been simplified and you will most likely have more code then just this in your `App.tsx` file. +:::note Note + +The above example has been simplified and you will most likely have more code then just this in your `App.tsx` file. + +::: ## Customize Actions @@ -162,7 +166,11 @@ const customActions: TableProps['actions'] = [ } /> ``` -> Note: the above example has been simplified and you will most likely have more code then just this in your `App.tsx` file. +:::note Note + +The above example has been simplified and you will most likely have more code then just this in your `App.tsx` file. + +::: The above customization will override the existing actions. Currently the only way to keep them and add your own is to also include the existing actions in your array by copying them from the [`defaultActions`](https://github.com/backstage/backstage/blob/57397e7d6d2d725712c439f4ab93f2ac6aa27bf8/plugins/catalog/src/components/CatalogTable/CatalogTable.tsx#L113-L168). @@ -400,7 +408,11 @@ export const CustomCatalogPage = () => { The above is a very basic version of a fully custom `CatalogIndexPage`, you'll want to explore the various props to see what you can all do with them. This was built off the building blocks seen in the [`DefaultCatalogPage`](https://github.com/backstage/backstage/blob/master/plugins/catalog/src/components/CatalogPage/DefaultCatalogPage.tsx) -> Note: The catalog index page is designed to have a minimal code footprint to support easy customization, but creating a replica does introduce a possibility of drifting out of date over time. Be sure to check the catalog [CHANGELOG](https://github.com/backstage/backstage/blob/master/plugins/catalog/CHANGELOG.md) periodically. +:::note Note + +The catalog index page is designed to have a minimal code footprint to support easy customization, but creating a replica does introduce a possibility of drifting out of date over time. Be sure to check the catalog [CHANGELOG](https://github.com/backstage/backstage/blob/master/plugins/catalog/CHANGELOG.md) periodically. + +::: To use this custom `CatalogIndexPage` which we called `CustomCatalogPage`, you'll need to make the following change: diff --git a/docs/features/software-catalog/life-of-an-entity.md b/docs/features/software-catalog/life-of-an-entity.md index d1c01141e4..13fe496fc1 100644 --- a/docs/features/software-catalog/life-of-an-entity.md +++ b/docs/features/software-catalog/life-of-an-entity.md @@ -162,9 +162,13 @@ steps and merging them into the final object which is what is visible from the catalog API. As the final entity itself gets updated, the stitcher makes sure that the search table gets refreshed accordingly as well. -> Note: The search table mentioned here is not related to the core Search -> feature of Backstage. It's rather the table that backs the ability to filter -> catalog API query results. +:::note Note + +The search table mentioned here is not related to the core Search +feature of Backstage. It's rather the table that backs the ability to filter +catalog API query results. + +::: ![Stitching overview](../../assets/features/catalog/life-of-an-entity_stitching.svg) diff --git a/docs/features/software-templates/adding-templates.md b/docs/features/software-templates/adding-templates.md index 6396d7530a..083516192c 100644 --- a/docs/features/software-templates/adding-templates.md +++ b/docs/features/software-templates/adding-templates.md @@ -86,12 +86,17 @@ contains more information about the required fields. Once we have a `template.yaml` ready, we can then add it to the software catalog for use by the scaffolder. -> Note: When you add or modify a template, you will need to refresh the location entity. -> Otherwise, Backstage won't display the template in the available templates, -> or it will keep showing the old template. You can refresh the location instance by -> going into `Catalog` web page, choosing `Locations` instead of `Components`, and selecting the correct location entity. -> From there, you can click on the refresh icon representing "Scheduled entity refresh" action. -> Afterwards, you should see your template updated. +:::note Note + +When you add or modify a template, you will need to refresh the location entity. +Otherwise, Backstage won't display the template in the available templates, +or it will keep showing the old template. You can refresh the location instance by +going into `Catalog` web page, choosing `Locations` instead of `Components`, and selecting the correct +location entity. +From there, you can click on the refresh icon representing "Scheduled entity refresh" action. +Afterwards, you should see your template updated. + +::: You can add the template files to the catalog through [static location configuration](../software-catalog/configuration.md#static-location-configuration), diff --git a/docs/features/software-templates/authorizing-parameters-steps-and-actions.md b/docs/features/software-templates/authorizing-parameters-steps-and-actions.md index 072f750a14..105c336538 100644 --- a/docs/features/software-templates/authorizing-parameters-steps-and-actions.md +++ b/docs/features/software-templates/authorizing-parameters-steps-and-actions.md @@ -229,4 +229,8 @@ backend.add(customPermissionBackendModule); /* highlight-add-end */ ``` -> Note: the `ExamplePermissionPolicy` here could be the one from the [Authorizing parameters and steps](#authorizing-parameters-and-steps) example or from the [Authorizing actions](#authorizing-actions) example. It would work the same way for both of them. +:::note Note + +The `ExamplePermissionPolicy` here could be the one from the [Authorizing parameters and steps](#authorizing-parameters-and-steps) example or from the [Authorizing actions](#authorizing-actions) example. It would work the same way for both of them. + +::: diff --git a/docs/features/software-templates/builtin-actions.md b/docs/features/software-templates/builtin-actions.md index 94b2d2298b..5b1e4347da 100644 --- a/docs/features/software-templates/builtin-actions.md +++ b/docs/features/software-templates/builtin-actions.md @@ -57,7 +57,11 @@ backend.add(import('@backstage/plugin-scaffolder-backend-module-github')); backend.start(); ``` -> Note: This is a simplified example of what your backend may look like, you may have more code in here then this. +:::note Note + +This is a simplified example of what your backend may look like, you may have more code in here then this. + +::: ## Listing Actions diff --git a/docs/features/software-templates/configuration.md b/docs/features/software-templates/configuration.md index 24b8c530b8..571f1150d0 100644 --- a/docs/features/software-templates/configuration.md +++ b/docs/features/software-templates/configuration.md @@ -12,7 +12,11 @@ This is done in your `app-config.yaml` by adding [Backstage integrations](https://backstage.io/docs/integrations/) for the appropriate source code repository for your organization. -> Note: Integrations may already be set up as part of your `app-config.yaml`. +:::note Note + +Integrations may already be set up as part of your `app-config.yaml`. + +::: The next step is to [add templates](http://backstage.io/docs/features/software-templates/adding-templates) to your Backstage app. diff --git a/docs/features/software-templates/index.md b/docs/features/software-templates/index.md index 9642214ede..d4fa6ac971 100644 --- a/docs/features/software-templates/index.md +++ b/docs/features/software-templates/index.md @@ -20,10 +20,14 @@ locations like GitHub or GitLab. > Be sure to have covered > [Getting Started with Backstage](../../getting-started) before proceeding. -> Note: if you're running Backstage with Node 20 or later, you'll need to pass the flag `--no-node-snapshot` to Node in order to -> use the templates feature. -> One way to do this is to specify the `NODE_OPTIONS` environment variable before starting Backstage: -> `export NODE_OPTIONS=--no-node-snapshot` +:::note Note + +If you're running Backstage with Node 20 or later, you'll need to pass the flag `--no-node-snapshot` to Node in order to +use the templates feature. +One way to do this is to specify the `NODE_OPTIONS` environment variable before starting Backstage: +`export NODE_OPTIONS=--no-node-snapshot` + +::: The Software Templates are available under `/create`. For local development you should be able to reach them at `http://localhost:3000/create`. diff --git a/docs/features/software-templates/migrating-to-rjsf-v5.md b/docs/features/software-templates/migrating-to-rjsf-v5.md index 829aaf8410..856841bdd4 100644 --- a/docs/features/software-templates/migrating-to-rjsf-v5.md +++ b/docs/features/software-templates/migrating-to-rjsf-v5.md @@ -5,7 +5,11 @@ title: 'Migrating to react-jsonschema-form@v5' description: Docs on migrating to `react-jsonschema-form`@v5 and the new designs --- -> Note: If you were previously using the `/alpha` imports to test out the `scaffolder/next` work, those imports have been promoted to the default exports from the respective packages. You should just have to remove the `/alpha` from the import path, and remove the `Next` from the import name. `NextScaffolderPage` -> `ScaffolderPage`, `createNextScaffolderFieldExtension` -> `createScaffolderFieldExtension` etc. +:::note Note + +If you were previously using the `/alpha` imports to test out the `scaffolder/next` work, those imports have been promoted to the default exports from the respective packages. You should just have to remove the `/alpha` from the import path, and remove the `Next` from the import name. `NextScaffolderPage` -> `ScaffolderPage`, `createNextScaffolderFieldExtension` -> `createScaffolderFieldExtension` etc. + +::: ## What's `react-jsonschema-form`? diff --git a/docs/features/software-templates/writing-custom-actions.md b/docs/features/software-templates/writing-custom-actions.md index 92ff092948..3b358e4c14 100644 --- a/docs/features/software-templates/writing-custom-actions.md +++ b/docs/features/software-templates/writing-custom-actions.md @@ -8,10 +8,14 @@ If you want to extend the functionality of the Scaffolder, you can do so by writing custom actions which can be used alongside our [built-in actions](./builtin-actions.md). -> Note: When adding custom actions, the actions array will **replace the -> built-in actions too**. Meaning, you will no longer be able to use them. -> If you want to continue using the builtin actions, include them in the actions -> array when registering your custom actions, as seen below. +:::note Note + +When adding custom actions, the actions array will **replace the +built-in actions too**. Meaning, you will no longer be able to use them. +If you want to continue using the builtin actions, include them in the actions +array when registering your custom actions, as seen below. + +::: ## Writing your Custom Action diff --git a/docs/features/techdocs/architecture.md b/docs/features/techdocs/architecture.md index 2cb8543ccd..8c9c4401cc 100644 --- a/docs/features/techdocs/architecture.md +++ b/docs/features/techdocs/architecture.md @@ -13,9 +13,14 @@ out-of-the box experience. ![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 -> [HOW TO migrate guide](how-to-guides.md#how-to-migrate-from-techdocs-basic-to-recommended-deployment-approach). +:::note Note + +See below for our recommended deployment architecture which takes care +of stability, scalability and speed. Also look at the +[HOW TO migrate guide](how-to-guides +md#how-to-migrate-from-techdocs-basic-to-recommended-deployment-approach). + +::: When you open a TechDocs site in Backstage, the [TechDocs Reader](./concepts.md#techdocs-reader) makes a request to diff --git a/docs/features/techdocs/getting-started.md b/docs/features/techdocs/getting-started.md index bf55c90af9..6cbbc83614 100644 --- a/docs/features/techdocs/getting-started.md +++ b/docs/features/techdocs/getting-started.md @@ -219,7 +219,11 @@ backend.add(import('@backstage/plugin-techdocs-backend/alpha')); backend.start(); ``` -> Note: The above is a very simplified example, you may have more content then this in your version. +:::note Note + +The above is a very simplified example, you may have more content then this in your version. + +::: ## Setting the configuration diff --git a/docs/features/techdocs/how-to-guides.md b/docs/features/techdocs/how-to-guides.md index b25c2a3928..3a7cfd97bb 100644 --- a/docs/features/techdocs/how-to-guides.md +++ b/docs/features/techdocs/how-to-guides.md @@ -499,8 +499,12 @@ Start writing your documentation by adding more markdown (.md) files to this folder (/docs) or replace the content in this file. ``` -> Note: The values of `site_name`, `component_id` and `site_description` depends -> on how you have configured your `template.yaml` +:::note Note + +The values of `site_name`, `component_id` and `site_description` depends +on how you have configured your `template.yaml`. + +::: Done! You now have support for TechDocs in your own software template! @@ -514,7 +518,11 @@ theme: font: false ``` -> Note: The addition `name: material` is necessary. Otherwise it will not work +:::note Note + +The addition `name: material` is necessary. Otherwise it will not work + +::: ## How to enable iframes in TechDocs @@ -623,12 +631,16 @@ plugins: - kroki ``` -> Note: you will very likely want to set a `kroki` `ServerURL` configuration in your -> `mkdocs.yml` as well. The default value is the publicly hosted `kroki.io`. If -> you have sensitive information in your organization's diagrams, you should set -> up a [server of your own](https://docs.kroki.io/kroki/setup/install/) and use it -> instead. Check out [mkdocs-kroki-plugin config](https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin#config) -> for more plugin configuration details. +:::note Note + +You will very likely want to set a `kroki` `ServerURL` configuration in your +`mkdocs.yml` as well. The default value is the publicly hosted `kroki.io`. If +you have sensitive information in your organization's diagrams, you should set +up a [server of your own](https://docs.kroki.io/kroki/setup/install/) and use it +instead. Check out [mkdocs-kroki-plugin config](https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin#config) +for more plugin configuration details. + +::: 4. **Add mermaid code into TechDocs:** @@ -766,7 +778,11 @@ backend.add(techdocsCustomBuildStrategy()); backend.start(); ``` -> Note: You may need to add the `@backstage/plugin-techdocs-node` package to your backend `package.json` if it's not been imported already. +:::note Note + +You may need to add the `@backstage/plugin-techdocs-node` package to your backend `package.json` if it's not been imported already. + +::: ## How to use other mkdocs plugins? diff --git a/docs/features/techdocs/using-cloud-storage.md b/docs/features/techdocs/using-cloud-storage.md index aaf2758241..6ba826ea62 100644 --- a/docs/features/techdocs/using-cloud-storage.md +++ b/docs/features/techdocs/using-cloud-storage.md @@ -169,17 +169,21 @@ permissions to: - `s3:ListBucket` - To retrieve bucket metadata - `s3:GetObject` - To retrieve files from the bucket -> Note: If you need to migrate documentation objects from an older-style path -> format including case-sensitive entity metadata, you will need to add some -> additional permissions to be able to perform the migration, including: -> -> - `s3:PutBucketAcl` (for copying files, -> [more info here](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObjectAcl.html)) -> - `s3:DeleteObject` and `s3:DeleteObjectVersion` (for deleting migrated files, -> [more info here](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObject.html)) -> -> ...And you will need to ensure the permissions apply to the bucket itself, as -> well as all resources under the bucket. See the example policy below. +:::note Note + +If you need to migrate documentation objects from an older-style path +format including case-sensitive entity metadata, you will need to add some +additional permissions to be able to perform the migration, including: + +- `s3:PutBucketAcl` (for copying files, + [more info here](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObjectAcl.html)) +- `s3:DeleteObject` and `s3:DeleteObjectVersion` (for deleting migrated files, + [more info here](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObject.html)) + +...And you will need to ensure the permissions apply to the bucket itself, as +well as all resources under the bucket. See the example policy below. + +::: ```json {