docs/releases/v1.45.0-next.1-changelog.md
Upgrade Helper: https://backstage.github.io/upgrade-helper/?to=1.45.0-next.1
mkdocs watch feature.@techdocs/cli serve command did not pick up the latest changes to TechDocs.@techdocs/cli serve command did not pick up the latest changes to TechDocs.@types/node@types/nodedockerode dependency.serveservets-node dev dependency.fs-extra to ^11.2.0.
Updated dependency @types/fs-extra to ^11.0.0.dockerode to ^4.0.0.commander to ^12.0.0.--runAsDefaultUser for @techdocs/cli generate to bypass running the docker builds as host user for macOS and Linux.mkdocs-server CLI parameters (--dirtyreload, --strict and --clean) when run in containerized mode.mkdocs-server CLI parameters (--dirtyreload, --strict and --clean) when run in containerized mode.--runAsDefaultUser for @techdocs/cli generate to bypass running the docker builds as host user for macOS and Linux.mkdocs.<yaml|yml> with the serve command using the --mkdocs-config-file-name` argument@types/node and mock-fs.mkdocs.<yaml|yml> with the serve command using the --mkdocs-config-file-name` argument@types/node and mock-fs.nodemon dependency.@techdocs/cli generate with the --verbose flag will now print the mkdocs output.@techdocs/cli generate with the --verbose flag will now print the mkdocs output.dd1e37649f: Deprecated getMkDocsYml in favor of getMkdocsYml (lowercase 'd')
dcacf94912: Fix proxying to mkdocs
The domain localhost may point to both 127.0.0.1 and ::1, ipv4 and ipv6 and when node tries to lookup localhost it might prefer ipv6 while mkdocs is only listening on ipv4. This tells node-proxy to target the ipv4 address instead of relying on localhost hostname lookup.
339d9a5b5c: Added support for using a default mkdocs.yml configuration file when none is provided
6e0b6a0d50: Fixed publish command missing awsBucketRootPath option. Fixed publish command having the gcsBucketRootPath option misconfigured, previously returning a boolean vs a string.
Updated dependencies
--preview-app-bundle-path and --preview-app-port options to the serve command enabling previewing with apps other than the provided one--preview-app-bundle-path and --preview-app-port options to the serve command enabling previewing with apps other than the provided one0b2a30dead: fixing techdocs-cli Docker client creation
Docker client does not need to be created when --no-docker option is provided.
If you had DOCKER_CERT_PATH environment variable defined the Docker client was looking for certificates and breaking techdocs-cli generate command even with --no-docker option.
Updated dependencies
0b2a30dead: fixing techdocs-cli Docker client creation
Docker client does not need to be created when --no-docker option is provided.
If you had DOCKER_CERT_PATH environment variable defined the Docker client was looking for certificates and breaking techdocs-cli generate command even with --no-docker option.
Updated dependencies
@types/jest.@types/jest.--docker-option to allow passing additional options to the docker run command executed my serve and serve:mkdocs.--docker-option to allow passing additional options to the docker run command executed my serve and serve:mkdocs.legacyCopyReadmeMdToIndexMd in techdocs-cli generate command, and decouple it's logic from the techdocs-ref flag.legacyCopyReadmeMdToIndexMd in techdocs-cli generate command, and decouple it's logic from the techdocs-ref flag.cypress to ^10.0.0.<SidebarPinStateProvider> + useSidebarPinState() and/or <SidebarOpenStateProvider> + useSidebarOpenState() from @backstage/core-components.cypress to ^10.0.0.<SidebarPinStateProvider> + useSidebarPinState() and/or <SidebarOpenStateProvider> + useSidebarOpenState() from @backstage/core-components.commander to version 9.1.0@backstage/plugin-techdocs-react package.techdocs-cli serve's proxyEndpoint to match the base URL of the embedded techdocs app.@backstage/plugin-techdocs-react package.commander to version 9.1.0733187987b: Removed an undocumented, broken behavior where README.md files would be copied to index.md if it did not exist, leading to broken links in the TechDocs UI.
WARNING: If you notice 404s in TechDocs after updating, check to make sure that all markdown files referenced in your mkdocs.ymls' nav sections exist. The following flag may be passed to the generate command to temporarily revert to the broken behavior.
techdocs-cli generate --legacyCopyReadmeMdToIndexMd
@types/node v16bcf1a2496c: BREAKING: The default Techdocs behavior will no longer attempt to copy docs/README.md or README.md to docs/index.md (if not found). To retain this behavior in your instance, you can set the following config in your app-config.yaml:
techdocs:
generator:
mkdocs:
legacyCopyReadmeMdToIndexMd: true
@types/node v16fs-extra from 9.1.0 to 10.0.1@backstage/plugin-techdocs-node package instead of @backstage/techdocs-common.fs-extra from 9.1.0 to 10.0.1@backstage/plugin-techdocs-node package instead of @backstage/techdocs-common.@backstage/techdocs-common to 0.11.10 to use spotify/techdocs:v0.3.7 which upgrades mkdocs-theme as a dependency of mkdocs-techdocs-core.cypress from 7.3.0 to 9.5.0github: location types in docs to use url: instead.cypress and cypress-plugin-snapshots as dependencies for integration and visual regression tests.
backstage.role to package.jsonreact-dev-utils from ^12.0.0-next.47 to ^12.0.0-next.60.index.html template was updated to use the new config global.dockerode and testcontainersReunified the techdocs-cli monorepo code back into the main backstage repo
See 7288). The changes include some internal refactoring that do not affect functionality beyond the local development setup.
8333394: The change updated the @backstage/techdocs-common from version 0.9.0 to 0.10.2 and one of the intermediate versions, the 0.10.0, introduced the use of search in context that requires an implementation for the Search API.
Created a custom techdocs page to disable search in the Reader component, preventing it from using the Search API, as we don't want to provide search in preview mode.
edbb988: Upgrades the techdocs common page to the latest version 0.10.2.
db4ebfc: Add an etag flag to the generate command that is stored in the techdocs_metadata.json file.
9d1f8d8: The techdocs-cli publish command will now publish TechDocs content to remote
storage using the lowercase'd entity triplet as the storage path. This is in
line with the beta release of the TechDocs plugin (v0.11.0).
If you have been running techdocs-cli prior to this version, you will need to
follow this migration guide.
f1bcf1a: Changelog (from v0.6.1 to v0.6.2)
techdocs-cli
techdocs-cli-embedded-app
Thank you for contributing ❤️
Emma Indal (@emmaindal)Min Kim (@minkimcello)Vitor Capretz (@vcapretz)dompurify to ^3.2.4.additionalAllowedURIProtocols to sanitizer configApiBlueprint.additionalAllowedURIProtocols to sanitizer configApiBlueprint.TechDocs plugin is now responsible for providing an entity icon link extension to read documentation from the catalog entity page.backstage.io/techdocs-entity-path annotation which allows deep linking into another entities TechDocs in conjunction with backstage.io/techdocs-entity.info.packageJson option to the plugin instance for the new frontend system.TechDocs plugin is now responsible for providing an entity icon link extension to read documentation from the catalog entity page.backstage.io/techdocs-entity-path annotation which allows deep linking into another entities TechDocs in conjunction with backstage.io/techdocs-entity.info.packageJson option to the plugin instance for the new frontend system.pluginId option of createFrontendPlugin.pluginId option of createFrontendPlugin.a47fd39: Removes instances of default React imports, a necessary update for the upcoming React 19 migration.
https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html
Updated dependencies
a47fd39: Removes instances of default React imports, a necessary update for the upcoming React 19 migration.
https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html
Updated dependencies
TechDocsAddonsBlueprint extension to allow adding of techdocs addons.TechDocsAddonsBlueprint extension to allow adding of techdocs addons.eb3d91a: Use the custom error page if provided for displaying errors instead of the default error page
524f0af: Add missing route ref to the /alpha entity content extension.
f4be934: Changed the base URL in addLinkClickListener from window.location.origin to app.baseUrl for improved path handling. This fixes an issue where Backstage, when running on a subpath, was unable to handle non-Backstage URLs of the same origin correctly.
1f40e6b: Add optional props to TechDocCustomHome to allow for more flexibility:
import { TechDocsCustomHome } from '@backstage/plugin-techdocs';
//...
const options = { emptyRowsWhenPaging: false };
const linkDestination = (entity: Entity): string | undefined => {
return entity.metadata.annotations?.['external-docs'];
};
const techDocsTabsConfig = [
{
label: 'Recommended Documentation',
panels: [
{
title: 'Golden Path',
description: 'Documentation about standards to follow',
panelType: 'DocsCardGrid',
panelProps: { CustomHeader: () => <ContentHeader title='Golden Path'/> },
filterPredicate: entity =>
entity?.metadata?.tags?.includes('golden-path') ?? false,
},
{
title: 'Recommended',
description: 'Useful documentation',
panelType: 'InfoCardGrid',
panelProps: {
CustomHeader: () => <ContentHeader title='Recommended' />
linkDestination: linkDestination,
},
filterPredicate: entity =>
entity?.metadata?.tags?.includes('recommended') ?? false,
},
],
},
{
label: 'Browse All',
panels: [
{
description: 'Browse all docs',
filterPredicate: filterEntity,
panelType: 'TechDocsIndexPage',
title: 'All',
panelProps: { PageWrapper: React.Fragment, CustomHeader: React.Fragment, options: options },
},
],
},
];
const AppRoutes = () => {
<FlatRoutes>
<Route
path="/docs"
element={
<TechDocsCustomHome
tabsConfig={techDocsTabsConfig}
filter={{
kind: ['Location', 'Resource', 'Component'],
'metadata.annotations.featured-docs': CATALOG_FILTER_EXISTS,
}}
CustomPageWrapper={({ children }: React.PropsWithChildren<{}>) => (<PageWithHeader title="Docs" themeId="documentation">{children}</PageWithHeader>)}
/>
}
/>
</FlatRoutes>;
};
Add new Grid option called InfoCardGrid which is a more customizable card option for the Docs grid.
<InfoCardGrid
entities={entities}
linkContent="Learn more"
linkDestination={entity => entity.metadata['external-docs']}
/>
Expose existing CustomDocsPanel so that it can be used independently if desired.
const panels: PanelConfig[] = [
{
description: '',
filterPredicate: entity => {},
panelType: 'InfoCardGrid',
title: 'Standards',
panelProps: {
CustomHeader: () => <ContentHeader title='Recommended' />
linkDestination: linkDestination,
},
},
{
description: '',
filterPredicate: entity => {},
panelType: 'DocsCardGrid',
title: 'Contribute',
},
];
{
panels.map((config, index) => (
<CustomDocsPanel
key={index}
config={config}
entities={!!entities ? entities : []}
index={index}
/>
));
}
58ec9e7: Removed older versions of React packages as a preparatory step for upgrading to React 19. This commit does not introduce any functional changes, but removes dependencies on previous React versions, allowing for a cleaner upgrade path in subsequent commits.
Updated dependencies
/alpha entity content extension.f4be934: Changed the base URL in addLinkClickListener from window.location.origin to app.baseUrl for improved path handling. This fixes an issue where Backstage, when running on a subpath, was unable to handle non-Backstage URLs of the same origin correctly.
1f40e6b: Add optional props to TechDocCustomHome to allow for more flexibility:
import { TechDocsCustomHome } from '@backstage/plugin-techdocs';
//...
const options = { emptyRowsWhenPaging: false };
const linkDestination = (entity: Entity): string | undefined => {
return entity.metadata.annotations?.['external-docs'];
};
const techDocsTabsConfig = [
{
label: 'Recommended Documentation',
panels: [
{
title: 'Golden Path',
description: 'Documentation about standards to follow',
panelType: 'DocsCardGrid',
panelProps: { CustomHeader: () => <ContentHeader title='Golden Path'/> },
filterPredicate: entity =>
entity?.metadata?.tags?.includes('golden-path') ?? false,
},
{
title: 'Recommended',
description: 'Useful documentation',
panelType: 'InfoCardGrid',
panelProps: {
CustomHeader: () => <ContentHeader title='Recommended' />
linkDestination: linkDestination,
},
filterPredicate: entity =>
entity?.metadata?.tags?.includes('recommended') ?? false,
},
],
},
{
label: 'Browse All',
panels: [
{
description: 'Browse all docs',
filterPredicate: filterEntity,
panelType: 'TechDocsIndexPage',
title: 'All',
panelProps: { PageWrapper: React.Fragment, CustomHeader: React.Fragment, options: options },
},
],
},
];
const AppRoutes = () => {
<FlatRoutes>
<Route
path="/docs"
element={
<TechDocsCustomHome
tabsConfig={techDocsTabsConfig}
filter={{
kind: ['Location', 'Resource', 'Component'],
'metadata.annotations.featured-docs': CATALOG_FILTER_EXISTS,
}}
CustomPageWrapper={({ children }: React.PropsWithChildren<{}>) => (<PageWithHeader title="Docs" themeId="documentation">{children}</PageWithHeader>)}
/>
}
/>
</FlatRoutes>;
};
Add new Grid option called InfoCardGrid which is a more customizable card option for the Docs grid.
<InfoCardGrid
entities={entities}
linkContent="Learn more"
linkDestination={entity => entity.metadata['external-docs']}
/>
Expose existing CustomDocsPanel so that it can be used independently if desired.
const panels: PanelConfig[] = [
{
description: '',
filterPredicate: entity => {},
panelType: 'InfoCardGrid',
title: 'Standards',
panelProps: {
CustomHeader: () => <ContentHeader title='Recommended' />
linkDestination: linkDestination,
},
},
{
description: '',
filterPredicate: entity => {},
panelType: 'DocsCardGrid',
title: 'Contribute',
},
];
{
panels.map((config, index) => (
<CustomDocsPanel
key={index}
config={config}
entities={!!entities ? entities : []}
index={index}
/>
));
}
Updated dependencies
withSearch prop to EntityTechdocsContent component since it was true by default, now user can use the EntityTechdocsContent component without showing the search field on top of the content.withSearch prop to EntityTechdocsContent component since it was true by default, now user can use the EntityTechdocsContent component without showing the search field on top of the content.<TechDocsReaderPageContent /> would re-render infinitely under certain conditions.canvas dev dependency.canvas dev dependency.@types/react to a peer dependency.emptyState input optional on entity-content:techdocs extension so that
the default empty state extension works correctly.git-url-parse to ^15.0.0.git-url-parse to ^15.0.0.@types/react to a peer dependency.emptyState input optional on entity-content:techdocs extension so that
the default empty state extension works correctly.c891b69: Add FavoriteToggle in core-components to standardise favorite marking
fec8b57: Updated exports to use the new type parameters for extensions and extension blueprints.
fe94ad8: Fixes left navigation positioning when using mkdocs blog plugin
b0206dc: Added support for setting page status with 'new' and 'deprecated' values, allowing visual indication of page status in TechDocs. To use include the following at the top of your markdown file:
---
status: new
---
836127c: Updated dependency @testing-library/react to ^16.0.0.
c7cb4c0: Add empty-state:techdocs/entity-content extension to allow overriding the empty state for the entity page techdocs tab.
97db53e: Enhanced the table hover effect with a lighter color and updated the border radius to align with Backstage's theme styling
Updated dependencies
FavoriteToggle in core-components to standardise favorite marking@testing-library/react to ^16.0.0.create*Extension, and replace it with the equivalent Blueprint implementation insteadmkdocs-redirects plugin. Redirects defined using the mkdocs-redirect plugin will be handled automatically in TechDocs. Redirecting to external urls is not supported. In the case that an external redirect url is provided, TechDocs will redirect to the current documentation site home.mkdocs-redirects plugin. Redirects defined using the mkdocs-redirect plugin will be handled automatically in TechDocs. Redirecting to external urls is not supported. In the case that an external redirect url is provided, TechDocs will redirect to the current documentation site home.fetchApi implementation for event source requests. This allows you to for example, override the Authorization header.TechDocsIndexPage now accepts an optional ownerPickerMode for toggling the behavior of the EntityOwnerPicker, exposing a new mode <TechDocsIndexPage ownerPickerMode="all" /> particularly suitable for larger catalogs. In this new mode, EntityOwnerPicker will display all the users and groups present in the catalog.CopyToClipboardButton component where positioning of the "Copy to clipboard" button in techdocs code snippets was broken in some cases.package.json.TechDocsSearchBar component from opening when clicking on the arrow icon.package.json.fetchApi implementation for event source requests. This allows you to for example, override the Authorization header.TechDocsIndexPage now accepts an optional ownerPickerMode for toggling the behavior of the EntityOwnerPicker, exposing a new mode <TechDocsIndexPage ownerPickerMode="all" /> particularly suitable for larger catalogs. In this new mode, EntityOwnerPicker will display all the users and groups present in the catalog.techdocs.builder config is now optional and it will default to local.techdocs.builder config is now optional and it will default to local.@testing-library/react to ^15.0.0.@testing-library/dom to ^10.0.0.no-top-level-material-ui-4-imports to aid with the migration to Material UI v5.<code> tags to avoid word break.convertLegacyRouteRefs to define routes in /alpha export plugin.@types/react dependency range to include version 18.dompurify to ^3.0.0.
Updated dependency @types/dompurify to ^3.0.0.git-url-parse to ^14.0.0.dompurify to ^3.0.0.
Updated dependency @types/dompurify to ^3.0.0.git-url-parse to ^14.0.0.@types/react dependency range to include version 18.<code> tags to avoid word break.convertLegacyRouteRefs to define routes in /alpha export plugin.convertLegacyRouteRef utility used by the alpha exports is now imported from @backstage/core-compat-api./alpha export extension elements in backwards compatibility wrapper./alpha exports to fit new naming patterns./alpha export extension elements in backwards compatibility wrapper.convertLegacyRouteRef utility used by the alpha exports is now imported from @backstage/core-compat-api.not-found will be published when a user visits a documentation site that does not exist@backstage/frontend-plugin-api./alpha.react-dom/client import to use import(...) rather than require(...).cross-fetch to ^4.0.0.createRoot API from react-dom/client will now be used if present.MissingAnnotationEmptyState from @backstage/plugin-catalog-react to remove the cyclical dependency17f93d5589 Thanks @agentbellnorm! - A new analytics event not-found will be published when a user visits a documentation site that does not exist#20842 fdb5e23602 Thanks @benjdlambert! - Import MissingAnnotationEmptyState from @backstage/plugin-catalog-react to remove the cyclical dependency
Updated dependencies
@backstage/frontend-plugin-api./alpha.react-dom/client import to use import(...) rather than require(...).createRoot API from react-dom/client will now be used if present./alpha subpath.TechDocsSearchResultItemExtension for declarative integration with Backstage; it can be accessed via the /alpha import.DocsTable to display pagination controls dynamically, appearing only when needed.@testing-library/jest-dom to ^6.0.0.@testing-library/dom to ^9.0.0.createRoot API from react-dom/client will now be used if present.DocsTable to display pagination controls dynamically, appearing only when needed.TechDocsSearchResultItemExtension for declarative integration with Backstage; it can be accessed via the /alpha import.backstage.io/techdocs-entity this ref allows you to reference another entity for its TechDocs. This allows you have a single TechDoc for all items in a system, for example you might have a frontend and a backend in the same repo. This would allow you to have TechDocs build under a System entity while referencing the system e.g.: backstage.io/techdocs-entity: system:default/example that will show the systems docs in both the TechDocs button and the TechDocs tab without needing to do duplicate builds and filling the TechDocs page with garbage.@types/node dependencybackstage.io/techdocs-entity this ref allows you to reference another entity for its TechDocs. This allows you have a single TechDoc for all items in a system, for example you might have a frontend and a backend in the same repo. This would allow you to have TechDocs build under a System entity while referencing the system e.g.: backstage.io/techdocs-entity: system:default/example that will show the systems docs in both the TechDocs button and the TechDocs tab without needing to do duplicate builds and filling the TechDocs page with garbage.@types/node dependencynotchedOutline class.plugin-techdocs-react pluginnotchedOutline class.plugin-techdocs-react plugin6c809d1a41c: Minor visual tweaks to adapt to changes in mkdocs-material v9
b2e182cdfa4: Fixes a UI bug in search result item which rendered the item text with incorrect font size and color
847a1eee3da: Change anchor links color in Techdocs content
With the color (mkdocs supplied) used for anchor links the background and foreground colors do not have a sufficient contrast ratio. Using the link color from theme palette.
8e00acb28db: Small tweaks to remove warnings in the console during development (mainly focusing on techdocs)
2e493480626: Fix a bug in sub-path navigation due to double addition of a sub-path if one was set up in app.baseUrl.
e0c6e8b9c3c: Update peer dependencies
Updated dependencies
app.baseUrl.6c809d1a41c: Minor visual tweaks to adapt to changes in mkdocs-material v9
847a1eee3da: Change anchor links color in Techdocs content
With the color (mkdocs supplied) used for anchor links the background and foreground colors do not have a sufficient contrast ratio. Using the link color from theme palette.
e0c6e8b9c3c: Update peer dependencies
Updated dependencies
LinkButton instead of the deprecated Buttonjss to ~10.10.0.msw to ^1.0.0.LinkButton instead of the deprecated Buttonjss to ~10.10.0.msw to ^1.0.0.TechDocsSearchResultListItem component is now a search result extension. This means that when rendered as a child of components that render search extensions, the result, rank, and highlight properties are optional. See the documentation for more details.c8e09cc383: Fixed bug in Techdocs reader where a techdocs page with a hash in the URL did not always jump to the document anchor.
cad5607411: Improve view: remove footer overlay on large screen
66e2aab4c4: ListItem wrapper component moved to SearchResultListItemExtension for all *SearchResultListItems that are exported as extensions. This is to make sure the list only contains list elements.
Note: If you have implemented a custom result list item, we recommend you to remove the list item wrapper to avoid nested <li> elements.
4660b63947: Create a TechDocs <LightBox/> addon that allows users to open images in a light-box on documentation pages, they can navigate between images if there are several on one page.
Here's an example on how to use it in a Backstage app:
import {
DefaultTechDocsHome,
TechDocsIndexPage,
TechDocsReaderPage,
} from '@backstage/plugin-techdocs';
import { TechDocsAddons } from '@backstage/plugin-techdocs-react/alpha';
+import { LightBox } from '@backstage/plugin-techdocs-module-addons-contrib';
const AppRoutes = () => {
<FlatRoutes>
// other plugin routes
<Route path="/docs" element={<TechDocsIndexPage />}>
<DefaultTechDocsHome />
</Route>
<Route
path="/docs/:namespace/:kind/:name/*"
element={<TechDocsReaderPage />}
>
<TechDocsAddons>
+ <LightBox />
</TechDocsAddons>
</Route>
</FlatRoutes>;
};
Updated dependencies
66e2aab4c4: ListItem wrapper component moved to SearchResultListItemExtension for all *SearchResultListItems that are exported as extensions. This is to make sure the list only contains list elements.
Note: If you have implemented a custom result list item, we recommend you to remove the list item wrapper to avoid nested <li> elements.
Updated dependencies
TechDocsSearchResultListItem component is now a search result extension. This means that when rendered as a child of components that render search extensions, the result, rank, and highlight properties are optional. See the documentation for more details.jss to ~10.9.0.jss to ~10.9.0.react-router-dom rather than react-router.react/forbid-elements linter rule for button, suggest Material UI Buttonmsw to ^0.49.0.react-router-dom rather than react-router.msw to ^0.49.0.5691baea69: Add ability to configure filters when using EntityListDocsGrid
The following example will render two sections of cards grid:
recommendedrunbook<EntityListDocsGrid groups={{[
{
title: "Recommended Documentation",
filterPredicate: entity =>
entity?.metadata?.tags?.includes('recommended') ?? false,
},
{
title: "RunBooks Documentation",
filterPredicate: entity =>
entity?.metadata?.tags?.includes('runbook') ?? false,
}
]}} />
63705e73d9: Hide document description if not provided
847fc588a6: Updated TechDocs header to include label for source code icon and updated label to reflect Kind name
canvas dependency to the latest version, which has better Node.js v18 support.GitHub with Github and deprecates old versions.click action is now captured when users click links within a TechDocs document.canvas dependency to the latest version, which has better Node.js v18 support.5691baea69: Add ability to configure filters when using EntityListDocsGrid
The following example will render two sections of cards grid:
recommendedrunbook<EntityListDocsGrid groups={{[
{
title: "Recommended Documentation",
filterPredicate: entity =>
entity?.metadata?.tags?.includes('recommended') ?? false,
},
{
title: "RunBooks Documentation",
filterPredicate: entity =>
entity?.metadata?.tags?.includes('runbook') ?? false,
}
]}} />
GitHub with Github and deprecates old versions.git-url-parse version to ^13.0.0@types/jest.TechDocsReaderPage to be compatible with React Router v6 stable.msw to ^0.47.0.msw to ^0.46.0.msw to ^0.45.0.SearchAutocomplete component in the TechDocsSearch component to maintain consistency across search experiences and avoid code duplication.TechDocs reader page.@types/jest.git-url-parse version to ^13.0.0msw to ^0.47.0.msw to ^0.46.0.SearchAutocomplete component in the TechDocsSearch component to maintain consistency across search experiences and avoid code duplication.TechDocsReaderPage to be compatible with React Router v6 stable.msw to ^0.45.0.TechDocs reader page.ebf3eb1641: Use the same initial filter owned for the TechDocsIndexPage as for the CatalogPage.
If you prefer to keep the previous behavior, you can change the default for the initial filter
to all (or starred if you rather prefer that).
<TechDocsIndexPage initiallySelectedFilter="all" />
In general, with this change you will be able to set props at TechDocsIndexPage.
a70869e775: Updated dependency msw to ^0.43.0.
8006d0f9bf: Updated dependency msw to ^0.44.0.
e2d7b76f43: Upgrade git-url-parse to 12.0.0.
Motivation for upgrade is transitively upgrading parse-url which is vulnerable to several CVEs detected by Snyk.
3cbebf710e: Reorder browser tab title in Techdocs pages to have the site name first.
726577958f: Remove the 60% factor from the font size calculation of headers to use the exact size defined in BackstageTheme.
7739141ab2: Fix: When docs are shown in an entity page under the docs tab the sidebars start overlapping with the header and tabs in the page when you scroll the documentation content.
Updated dependencies
msw to ^0.43.0.e2d7b76f43: Upgrade git-url-parse to 12.0.0.
Motivation for upgrade is transitively upgrading parse-url which is vulnerable to several CVEs detected by Snyk.
7739141ab2: Fix: When docs are shown in an entity page under the docs tab the sidebars start overlapping with the header and tabs in the page when you scroll the documentation content.
Updated dependencies
d047d81295: Use entity title as label in TechDocsReaderPageHeader if available
8f7b1835df: Updated dependency msw to ^0.41.0.
bff65e6958: Updated sidebar-related logic to use <SidebarPinStateProvider> + useSidebarPinState() and/or <SidebarOpenStateProvider> + useSidebarOpenState() from @backstage/core-components.
915700f64f: In order to simplify analytics on top of the search experience in Backstage, the provided <*ResultListItem /> component now captures a discover analytics event instead of a click event. This event includes the result rank as its value and, like a click, the URL/path clicked to as its to attribute.
881fbd7e8d: Fix EntityTechdocsContent component to use objects instead of <Route> elements, otherwise "outlet" will be null on sub-pages and add-ons won't render.
17c059dfd0: Restructures reader style transformations to improve code readability:
3b45ad701f: Packages a set of tweaks to the TechDocs addons rendering process:
9b94ade898: Use entity title in TechDocsSearch placeholder if available.
816f7475ec: Convert sanitizeDOM transformer to hook as part of code readability improvements in dom file.
50ff56a80f: Change the EntityDocsPage path to be more specific and also add integration tests for sub-routes on this page.
Updated dependencies
msw to ^0.41.0.<SidebarPinStateProvider> + useSidebarPinState() and/or <SidebarOpenStateProvider> + useSidebarOpenState() from @backstage/core-components.881fbd7e8d: Fix EntityTechdocsContent component to use objects instead of <Route> elements, otherwise "outlet" will be null on sub-pages and add-ons won't render.
17c059dfd0: Restructures reader style transformations to improve code readability:
3b45ad701f: Packages a set of tweaks to the TechDocs addons rendering process:
816f7475ec: Convert sanitizeDOM transformer to hook as part of code readability improvements in dom file.
50ff56a80f: Change the EntityDocsPage path to be more specific and also add integration tests for sub-routes on this page.
Updated dependencies
@backstage/core-app-api.sub-route path on the EntityDocs page to fix the blank screen error when navigating using sidebar links.bota with extended charactersTechDocsStorageApi and its associated ref are now exported by @backstage/plugin-techdocs-react. The API interface, ref, and types are now deprecated in @backstage/plugin-techdocs and will be removed in a future release.event-source-polyfill to 1.0.25event-source-polyfill to 1.0.26.bota with extended charactersTechDocsStorageApi and its associated ref are now exported by @backstage/plugin-techdocs-react. The API interface, ref, and types are now deprecated in @backstage/plugin-techdocs and will be removed in a future release.@backstage/core-app-api.ace749b785: TechDocs supports a new, experimental method of customization: addons!
To customize the standalone TechDocs reader page experience, update your /packages/app/src/App.tsx in the following way:
import { TechDocsIndexPage, TechDocsReaderPage } from '@backstage/plugin-techdocs';
+ import { TechDocsAddons } from '@backstage/plugin-techdocs-react';
+ import { SomeAddon } from '@backstage/plugin-some-plugin';
// ...
<Route path="/docs" element={<TechDocsIndexPage />} />
<Route
path="/docs/:namespace/:kind/:name/*"
element={<TechDocsReaderPage />}
>
+ <TechDocsAddons>
+ <SomeAddon />
+ </TechDocsAddons>
</Route>
// ...
To customize the TechDocs reader experience on the Catalog entity page, update your packages/app/src/components/catalog/EntityPage.tsx in the following way:
import { EntityTechdocsContent } from '@backstage/plugin-techdocs';
+ import { TechDocsAddons } from '@backstage/plugin-techdocs-react';
+ import { SomeAddon } from '@backstage/plugin-some-plugin';
// ...
<EntityLayoutWrapper>
<EntityLayout.Route path="/" title="Overview">
{overviewContent}
</EntityLayout.Route>
<EntityLayout.Route path="/docs" title="Docs">
- <EntityTechDocsContent />
+ <EntityTechdocsContent>
+ <TechDocsAddons>
+ <SomeAddon />
+ </TechDocsAddons>
+ </EntityTechdocsContent>
</EntityLayout.Route>
</EntityLayoutWrapper>
// ...
If you do not wish to customize your TechDocs reader experience in this way at this time, no changes are necessary!
ab230a433f: imports from @backstage/plugin-search-react instead of @backstage/plugin-search
7c7919777e: build(deps-dev): bump @testing-library/react-hooks from 7.0.2 to 8.0.0
24254fd433: build(deps): bump @testing-library/user-event from 13.5.0 to 14.0.0
230ad0826f: Bump to using @types/node v16
f0fb9153b7: Fix broken query selectors on techdocs
9975ff9852: Applied the fix from version 1.0.1 of this package, which is part of the v1.0.2 release of Backstage.
3ba256c389: Fixed a bug preventing custom TechDocs reader page implementations from rendering without being double-wrapped in the <TechDocsReaderPage /> component.
fe53fe97d7: Fix permalink scrolling for anchors where the id starts with a number.
0152c0de22: Some documentation layout tweaks:
3ba256c389: Fixed a bug that caused addons in the Subheader location to break the default TechDocs reader page layout.
Updated dependencies
ace749b785: TechDocs supports a new, experimental method of customization: addons!
To customize the standalone TechDocs reader page experience, update your /packages/app/src/App.tsx in the following way:
import { TechDocsIndexPage, TechDocsReaderPage } from '@backstage/plugin-techdocs';
+ import { TechDocsAddons } from '@backstage/plugin-techdocs-react';
+ import { SomeAddon } from '@backstage/plugin-some-plugin';
// ...
<Route path="/docs" element={<TechDocsIndexPage />} />
<Route
path="/docs/:namespace/:kind/:name/*"
element={<TechDocsReaderPage />}
>
+ <TechDocsAddons>
+ <SomeAddon />
+ </TechDocsAddons>
</Route>
// ...
To customize the TechDocs reader experience on the Catalog entity page, update your packages/app/src/components/catalog/EntityPage.tsx in the following way:
import { EntityTechdocsContent } from '@backstage/plugin-techdocs';
+ import { TechDocsAddons } from '@backstage/plugin-techdocs-react';
+ import { SomeAddon } from '@backstage/plugin-some-plugin';
// ...
<EntityLayoutWrapper>
<EntityLayout.Route path="/" title="Overview">
{overviewContent}
</EntityLayout.Route>
<EntityLayout.Route path="/docs" title="Docs">
- <EntityTechDocsContent />
+ <EntityTechdocsContent>
+ <TechDocsAddons>
+ <SomeAddon />
+ </TechDocsAddons>
+ </EntityTechdocsContent>
</EntityLayout.Route>
</EntityLayoutWrapper>
// ...
If you do not wish to customize your TechDocs reader experience in this way at this time, no changes are necessary!
@backstage/plugin-search-react instead of @backstage/plugin-search@testing-library/user-event from 13.5.0 to 14.0.0@types/node v16event-source-polyfill dependency to version 1.0.250152c0de22: Some documentation layout tweaks:
Updated dependencies
700d93ff41: Removed deprecated exports, including:
DocsResultListItem is now deleted and fully replaced with TechDocsSearchResultListItemTechDocsPage is now deleted and fully replaced with TechDocsReaderPageTechDocsPageHeader is now deleted and fully replaced with TechDocsReaderPageHeaderTechDocsPageHeaderProps is now deleted and fully replaced with TechDocsReaderPageHeaderPropsTechDocsPageRenderFunction is now deleted and fully replaced with TechDocsReaderPageRenderFunctiontechdocs.requestUrl is now deleted and fully replaced with the discoveryApi@testing-library/react from 11.2.6 to 12.1.3CatalogFilterLayout from @backstage/plugin-catalog-react.TechDocsCustomHome now use the useEntityOwnership hook to resolve ownership when the 'ownedByUser' filter predicate is used.TechDocsCustomHome now use the useEntityOwnership hook to resolve ownership when the 'ownedByUser' filter predicate is used.ee3d6c6f10: BREAKING:
Table column utilities createNameColumn, createOwnerColumn, createTypeColumn as well as actions utilities createCopyDocsUrlAction and createStarEntityAction are no longer directly exported. Instead accessible through DocsTable and EntityListDocsTable.
Use as following:
DocsTable.columns.createNameColumn();
DocsTable.columns.createOwnerColumn();
DocsTable.columns.createTypeColumn();
DocsTable.actions.createCopyDocsUrlAction();
DocsTable.actions.createStarEntityAction();
Renamed DocsResultListItem to TechDocsSearchResultListItem, leaving the old name in place as a deprecations.
Renamed TechDocsPage to TechDocsReaderPage, leaving the old name in place as a deprecations.
Renamed TechDocsPageRenderFunction to TechDocsPageRenderFunction, leaving the old name in place as a deprecations.
Renamed TechDocsPageHeader to TechDocsReaderPageHeader, leaving the old name in place as a deprecations.
LegacyTechDocsHome marked as deprecated and will be deleted in next release, use TechDocsCustomHome instead.
LegacyTechDocsPage marked as deprecated and will be deleted in next release, use TechDocsReaderPage instead.
react-text-truncate from 0.17.0 to 0.18.0getEntityByRef instead of getEntityByName in the catalog clientformatEntityRefTitle in favor of the new humanizeEntityRef method instead. Please migrate to using the new method instead.mkdocs-techdocs-plugin (v0.2.2).CompoundEntityRef instead of EntityName, and getCompoundEntityRef instead of getEntityName, from @backstage/catalog-model.2262fe19c9: BREAKING: Removed support for passing in an explicit entity prop to entity page extensions, which has been deprecated for a long time. This is only a breaking change at the TypeScript level, as this property was already ignored.
4faae902eb: Adjust the Tech Docs page theme as a side effect of the mkdocs-material theme update.
If you use the spofify/techdocs image to build your documentation, make sure you use version spotify/techdocs:v0.3.7.
Breaking: The PyMdown extensions have also been updated and some syntax may have changed, so it is recommended that you check the extension's documentation if something stops working.
For example, the syntax of tags below was deprecated in PyMdown extensions v.7.0 and in v.8.0.0 it has been removed. This means that the old syntax specified below no longer works.
```markdown tab="tab"
This is some markdown
```
```markdown tab="tab 2"
This is some markdown in tab 2
```
LocationSpec type from @backstage/catalog-model, which is deprecated.useEntityListProvider hook with useEntityList.targetRef field of relations, and to stop consuming the target fieldnode-fetch to version 2.6.7 and cross-fetch to version 3.1.5backstage.role to package.jsondownload attribute would result in a 404 in cases where the TechDocs backend and Backstage frontend application are on the same host.<source> tag to point to relative resources like audio or video files.download attribute would result in a 404 in cases where the TechDocs backend and Backstage frontend application are on the same host.<source> tag to point to relative resources like audio or video files.react-text-truncate from 0.16.0 to 0.17.0aecfe4f403: Make TechDocsClient and TechDocsStorageClient use the FetchApi. You now
need to pass in an instance of that API when constructing the client, if you
create a custom instance in your app.
If you are replacing the factory:
+import { fetchApiRef } from '@backstage/core-plugin-api';
createApiFactory({
api: techdocsStorageApiRef,
deps: {
configApi: configApiRef,
discoveryApi: discoveryApiRef,
identityApi: identityApiRef,
+ fetchApi: fetchApiRef,
},
factory: ({
configApi,
discoveryApi,
identityApi,
+ fetchApi,
}) =>
new TechDocsStorageClient({
configApi,
discoveryApi,
identityApi,
+ fetchApi,
}),
}),
createApiFactory({
api: techdocsApiRef,
deps: {
configApi: configApiRef,
discoveryApi: discoveryApiRef,
- identityApi: identityApiRef,
+ fetchApi: fetchApiRef,
},
factory: ({
configApi,
discoveryApi,
- identityApi,
+ fetchApi,
}) =>
new TechDocsClient({
configApi,
discoveryApi,
- identityApi,
+ fetchApi,
}),
}),
If instantiating directly:
+import { fetchApiRef } from '@backstage/core-plugin-api';
+const fetchApi = useApi(fetchApiRef);
const storageClient = new TechDocsStorageClient({
configApi,
discoveryApi,
identityApi,
+ fetchApi,
});
const techdocsClient = new TechDocsClient({
configApi,
discoveryApi,
- identityApi,
+ fetchApi,
}),
IdentityApi methods.IdentityApi methods.react-use imports to use react-use/lib/* instead.peerDependencies and allow both React v16 and v17 to be used.LogViewer component from @backstage/core-components to display build logs.bab752e2b3: Change default port of backend from 7000 to 7007.
This is due to the AirPlay Receiver process occupying port 7000 and preventing local Backstage instances on MacOS to start.
You can change the port back to 7000 or any other value by providing an app-config.yaml with the following values:
backend:
listen: 0.0.0.0:7123
baseUrl: http://localhost:7123
More information can be found here: https://backstage.io/docs/conf/writing
Updated dependencies
LazyLog as it is rarely used.kind, namespace and name in DefaultTechDocsCollator.ba5b75ed2f: Add <EntityListDocsGrid> as an alternative to <EntityListDocsTable> that
shows a grid of card instead of table.
Extend <DocsCardGrid> to display the entity title of the entity instead of the
name if available.
177401b571: Display entity title (if defined) in titles of TechDocs search results
cdf8ca6111: Only replace the shadow dom if the content is changed to avoid a flickering UI.
Updated dependencies
<Reader /> component internals to support future extensibility.name key to all extensions in order to improve Analytics API metadata.82bb0842a3: Adds support for being able to customize and compose your TechDocs reader page in the App.
You can likely upgrade to this version without issue. If, however, you have
imported the <Reader /> component in your custom code, the name of a property
has changed. You will need to make the following change anywhere you use it:
-<Reader entityId={value} />
+<Reader entityRef={value} />
@material-ui/lab to 4.0.0-alpha.57.30ed662a3: Adding in-context search to TechDocs Reader component. Using existing search-backend to query for indexed search results scoped into a specific entity's techdocs. Needs TechDocsCollator enabled on the backend to work.
Adding extra information to indexed tech docs documents for search.
434dfc5d4: Display metadata.title for components on the TechDocs homepage, if defined; otherwise fall back to metadata.name as displayed before.
Updated dependencies
c772d9a84: TechDocs sites can now be accessed using paths containing entity triplets of
any case (e.g. /docs/namespace/KIND/name or /docs/namespace/kind/name).
If you do not use an external storage provider for serving TechDocs, this is a transparent change and no action is required from you.
If you do use an external storage provider for serving TechDocs (one of* GCS, AWS S3, or Azure Blob Storage), you must run a migration command against your storage provider before updating.
A migration guide is available here.
787bc0826: The TechDocs plugin has completed the migration to the Composability API. In
order to update to this version, please ensure you've made all necessary
changes to your App.tsx file as outlined in the create-app changelog.
a440d3b38: Expose a new composable TechDocsIndexPage and a DefaultTechDocsHome with support for starring docs and filtering on owned, starred, owner, and tags.
You can migrate to the new UI view by making the following changes in your App.tsx:
- <Route path="/docs" element={<TechdocsPage />} />
+ <Route path="/docs" element={<TechDocsIndexPage />}>
+ <DefaultTechDocsHome />
+ </Route>
+ <Route
+ path="/docs/:namespace/:kind/:name/*"
+ element={<TechDocsReaderPage />}
+ />
56c773909: Switched @types/react dependency to request * rather than a specific version.
8a3e46591: Switch EventSource implementation with header support from a Node.js API-based one to an XHR-based one.
Updated dependencies
material-ui/core version to at least 4.12.2 as they made some breaking changes in later versions which broke Pagination of the Table.
material-table to @material-table/core for support for the later versions of material-ui/core@backstage/core-components as the interface for Table re-exports the prop from the underlying Table components.onChangeRowsPerPage has been renamed to onRowsPerPageChangeonChangePage has been renamed to onPageChangebackstage.io/techdocs-ref annotation9266b80ab: Add search list item to display tech docs search results
03bf17e9b: Improve the responsiveness of the EntityPage UI. With this the Header component should scale with the screen size & wrapping should not cause overflowing/blocking of links. Additionally enforce the Pages using the Grid Layout to use it across all screen sizes & to wrap as intended.
To benefit from the improved responsive layout, the EntityPage in existing Backstage applications should be updated to set the xs column size on each grid item in the page, as this does not default. For example:
- <Grid item md={6}>
+ <Grid item xs={12} md={6}>
378cc6a54: Only update the path when the content is updated.
If content and path are updated independently, the frontend rendering is triggered twice on each navigation: Once for the path change (with the old content) and once for the new content.
This might result in a flickering rendering that is caused by the async frontend preprocessing, and the fact that replacing the shadow dom content is expensive.
214e7c52d: Refactor the techdocs transformers to return Promises and await all transformations.
e35b13afa: Handle error responses in getTechDocsMetadata and getEntityMetadata such that <TechDocsPageHeader> doesn't throw errors.
Updated dependencies
94a54dd47: Added a migrateDocsCase() method to TechDocs publishers, along with
implementations for AWS, Azure, and GCS.
This change is in support of a future update to TechDocs that will allow for case-insensitive entity triplet URL access to documentation pages which will require a migration of existing documentation objects in external storage solutions.
See #4367 for details.
/sync/:namespace/:kind/:name endpoint to support an event-stream as response.
This change allows the sync process to take longer than a normal HTTP timeout.
The stream also emits log events, so the caller can follow the build process in the frontend.@backstage/core-* packages rather than @backstage/core.<Reader /> into an explicit state machine. This resolves some state synchronization issues when content is refreshed or rebuilt in the backend.download attribute on anchor tags in generated
markup, allowing documentation authors to bundle downloadable files with their
documentation.#hash correctly when rewriting link URLs.@testing-library/user-event from 12.8.3 to 13.1.8react-use dependency in all packages21fddf452: Make techdocsStorageApiRef and techdocsApiRef use interfaces instead of the
actual implementation classes.
This renames the classes TechDocsApi to TechDocsClient and TechDocsStorageApi
to TechDocsStorageClient and renames the interfaces TechDocs to TechDocsApi
and TechDocsStorage to TechDocsStorageApi to comply the pattern elsewhere in
the project. This also fixes the types returned by some methods on those
interfaces.
EntityRefLink in header and use relations to reference the owner of the
document.repo_url and edit_uri to be filled in mkdocs.yml, as per https://www.mkdocs.org/user-guide/configuration. An edit_uri will need to be specified for self-hosted GitLab/GitHub instances with a different host name.
To identify issue URL format as GitHub or GitLab, the host name of source in repo_url is checked if it contains gitlab or github. Alternately this is determined by matching to host values from integrations in app-config.yaml.@backstage/techdocs-common dependency to not pull in backend config schemas in the frontend.ItemCardGrid and ItemCardHeader instead of the deprecated ItemCard.techdocs.publisher.awsS3.endpointattr and cleaned up a bit in the TechDocs config schema.techdocsPlugin, the top-level page as TechdocsPage, and the entity content as EntityTechdocsContent.href in addition to onClick to ItemCard. Ensure that the height of a
ItemCard with and without tags is equal.techdocs.requestUrl and techdocs.storageUrl are now optional configs and the discovery API will be used to get the URL where techdocs plugin is hosted.@backstage/plugin-catalog to @backstage/plugin-catalog-react.a5e27d5c1: Create type for TechDocsMetadata (#3716)
This change introduces a new type (TechDocsMetadata) in packages/techdocs-common. This type is then introduced in the endpoint response in techdocs-backend and in the api interface in techdocs (frontend).
Updated dependencies [def2307f3]
Updated dependencies [efd6ef753]
Updated dependencies [593632f07]
Updated dependencies [33846acfc]
Updated dependencies [a187b8ad0]
Updated dependencies [f04db53d7]
Updated dependencies [53c9c51f2]
Updated dependencies [a5e27d5c1]
Updated dependencies [a93f42213]
dbe4450c3: Google Cloud authentication in TechDocs has been improved.
techdocs.publisher.googleGcs.credentials is now optional. If it is missing, GOOGLE_APPLICATION_CREDENTIALS
environment variable (and some other methods) will be used to authenticate.
Read more here https://cloud.google.com/docs/authentication/production
techdocs.publisher.googleGcs.projectId is no longer used. You can remove it from your app-config.yaml.
a6f9dca0d: Remove dependency on @backstage/core-api. No plugin should ever depend on that package; it's an internal concern whose important bits are re-exported by @backstage/core which is the public facing dependency to use.
b3b9445df: AWS S3 authentication in TechDocs has been improved.
techdocs.publisher.awsS3.bucketName is now the only required config. techdocs.publisher.awsS3.credentials and techdocs.publisher.awsS3.region are optional.
If techdocs.publisher.awsS3.credentials and techdocs.publisher.awsS3.region are missing, the AWS environment variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_REGION will be used. There are more better ways of setting up AWS authentication. Read the guide at https://backstage.io/docs/features/techdocs/using-cloud-storage
e5d12f705: Use history.pushState for hash link navigation.
Updated dependencies [68ad5af51]
Updated dependencies [f3b064e1c]
Updated dependencies [371f67ecd]
Updated dependencies [f1e74777a]
Updated dependencies [dbe4450c3]
Updated dependencies [c00488983]
Updated dependencies [265a7ab30]
Updated dependencies [5826d0973]
Updated dependencies [b3b9445df]
Updated dependencies [abbee6fff]
Updated dependencies [147fadcb9]
dae4f3983: Breaking changes
Added option to use Google Cloud Storage as a choice to store the static generated files for TechDocs.
It can be configured using techdocs.publisher.type option in app-config.yaml.
Step-by-step guide to configure GCS is available here https://backstage.io/docs/features/techdocs/using-cloud-storage
Set techdocs.publisher.type to 'local' if you want to continue using local filesystem to store TechDocs files.
techdocs.builder is now required and can be set to 'local' or 'external'. (Set it to 'local' for now, since CI/CD build
workflow for TechDocs will be available soon (in few weeks)).
If builder is set to 'local' and you open a TechDocs page, techdocs-backend will try to generate the docs, publish to storage and
show the generated docs afterwords.
If builder is set to 'external', techdocs-backend will only fetch the docs and will NOT try to generate and publish. In this case of 'external',
we assume that docs are being built in the CI/CD pipeline of the repository.
TechDocs will not assume a default value for techdocs.builder. It is better to explicitly define it in the app-config.yaml.
When configuring TechDocs in your backend, there is a difference in how a new publisher is created.
--- const publisher = new LocalPublish(logger, discovery); +++ const publisher = Publisher.fromConfig(config, logger, discovery);
Based on the config techdocs.publisher.type, the publisher could be either Local publisher or Google Cloud Storage publisher.
techdocs.storageUrl is now a required config. Should be http://localhost:7000/api/techdocs/static/docs in most setups.
Parts of @backstage/plugin-techdocs-backend have been moved to a new package @backstage/techdocs-common to generate docs. Also to publish docs
to-and-fro between TechDocs and a storage (either local or external). However, a Backstage app does NOT need to import the techdocs-common package -
app should only import @backstage/plugin-techdocs and @backstage/plugin-techdocs-backend.
Patch changes
See all of TechDocs config options and its documentation https://backstage.io/docs/features/techdocs/configuration
Logic about serving static files and metadata retrieval have been abstracted away from the router in techdocs-backend to the instance of publisher.
Removed Material UI Spinner from TechDocs header. Spinners cause unnecessary UX distraction. Case 1 (when docs are built and are to be served): Spinners appear for a split second before the name of site shows up. This unnecessarily distracts eyes because spinners increase the size of the Header. A dot (.) would do fine. Definitely more can be done. Case 2 (when docs are being generated): There is already a linear progress bar (which is recommended in Storybook).
/metadata/mkdocs/* renamed to /metadata/techdocs/*28edd7d29: Create backend plugin through CLI
8351ad79b: Add a message if techdocs takes long time to load
Fixes #2416.
The UI after the change should look like this:
5c614ff: BREAKING: Migrated Checkbox component from Base UI to React Aria Components.
API changes required:
checked → isSelecteddefaultChecked → defaultSelecteddisabled → isDisabledrequired → isRequiredlabel prop removed - use children insteadbui-CheckboxLabel class removeddata-checked → data-selectedMigration examples:
Before:
<Checkbox label="Accept terms" checked={agreed} onChange={setAgreed} />
After:
<Checkbox isSelected={agreed} onChange={setAgreed}>
Accept terms
</Checkbox>
Before:
<Checkbox label="Option" disabled />
After:
<Checkbox isDisabled>Option</Checkbox>
Before:
<Checkbox />
After:
<Checkbox>
<VisuallyHidden>Accessible label</VisuallyHidden>
</Checkbox>
b78fc45: BREAKING: Changed className prop behavior to augment default styles instead of being ignored or overriding them.
Affected components:
If you were passing custom className values to any of these components that relied on the previous behavior, you may need to adjust your styles to account for the default classes now being applied alongside your custom classes.
*.css.AWS SES client to version 2 to support nodemailer version 7.erasableSyntaxOnly setting. This internal refactoring maintains all existing functionality while ensuring TypeScript compilation compatibility.nodemailer from 6.9.16 to 7.0.7nodemailer from 6.9.16 to 7.0.7ses mail options with sourceArn, fromArn, configurationSetNameses mail options with sourceArn, fromArn, configurationSetNamecatalogServiceRefcatalogServiceRefd425fc4: BREAKING: The return values from createBackendPlugin, createBackendModule, and createServiceFactory are now simply BackendFeature and ServiceFactory, instead of the previously deprecated form of a function that returns them. For this reason, createServiceFactory also no longer accepts the callback form where you provide direct options to the service. This also affects all coreServices.* service refs.
This may in particular affect tests; if you were effectively doing createBackendModule({...})() (note the parentheses), you can now remove those extra parentheses at the end. You may encounter cases of this in your packages/backend/src/index.ts too, where you add plugins, modules, and services. If you were using createServiceFactory with a function as its argument for the purpose of passing in options, this pattern has been deprecated for a while and is no longer supported. You may want to explore the new multiton patterns to achieve your goals, or moving settings to app-config.
As part of this change, the IdentityFactoryOptions type was removed, and can no longer be used to tweak that service. The identity service was also deprecated some time ago, and you will want to migrate to the new auth system if you still rely on it.
d425fc4: BREAKING: The return values from createBackendPlugin, createBackendModule, and createServiceFactory are now simply BackendFeature and ServiceFactory, instead of the previously deprecated form of a function that returns them. For this reason, createServiceFactory also no longer accepts the callback form where you provide direct options to the service. This also affects all coreServices.* service refs.
This may in particular affect tests; if you were effectively doing createBackendModule({...})() (note the parentheses), you can now remove those extra parentheses at the end. You may encounter cases of this in your packages/backend/src/index.ts too, where you add plugins, modules, and services. If you were using createServiceFactory with a function as its argument for the purpose of passing in options, this pattern has been deprecated for a while and is no longer supported. You may want to explore the new multiton patterns to achieve your goals, or moving settings to app-config.
As part of this change, the IdentityFactoryOptions type was removed, and can no longer be used to tweak that service. The identity service was also deprecated some time ago, and you will want to migrate to the new auth system if you still rely on it.
def53a7: BREAKING Following NotificationTemplateRenderer methods now return a Promise and must be awaited: getSubject, getText and getHtml.
Required changes and example usage:
import { notificationsEmailTemplateExtensionPoint } from '@backstage/plugin-notifications-backend-module-email';
import { Notification } from '@backstage/plugin-notifications-common';
+import { getNotificationSubject, getNotificationTextContent, getNotificationHtmlContent } from 'my-notification-processing-library`
export const notificationsModuleEmailDecorator = createBackendModule({
pluginId: 'notifications',
moduleId: 'email.templates',
register(reg) {
reg.registerInit({
deps: {
emailTemplates: notificationsEmailTemplateExtensionPoint,
},
async init({ emailTemplates }) {
emailTemplates.setTemplateRenderer({
- getSubject(notification) {
+ async getSubject(notification) {
- return `New notification from ${notification.source}`;
+ const subject = await getNotificationSubject(notification);
+ return `New notification from ${subject}`;
},
- getText(notification) {
+ async getText(notification) {
- return notification.content;
+ const text = await getNotificationTextContent(notification);
+ return text;
},
- getHtml(notification) {
+ async getHtml(notification) {
- return `<p>${notification.content}</p>`;
+ const html = await getNotificationHtmlContent(notification);
+ return html;
},
});
},
});
},
});
def53a7: BREAKING Following NotificationTemplateRenderer methods now return a Promise and must be awaited: getSubject, getText and getHtml.
Required changes and example usage:
import { notificationsEmailTemplateExtensionPoint } from '@backstage/plugin-notifications-backend-module-email';
import { Notification } from '@backstage/plugin-notifications-common';
+import { getNotificationSubject, getNotificationTextContent, getNotificationHtmlContent } from 'my-notification-processing-library`
export const notificationsModuleEmailDecorator = createBackendModule({
pluginId: 'notifications',
moduleId: 'email.templates',
register(reg) {
reg.registerInit({
deps: {
emailTemplates: notificationsEmailTemplateExtensionPoint,
},
async init({ emailTemplates }) {
emailTemplates.setTemplateRenderer({
- getSubject(notification) {
+ async getSubject(notification) {
- return `New notification from ${notification.source}`;
+ const subject = await getNotificationSubject(notification);
+ return `New notification from ${subject}`;
},
- getText(notification) {
+ async getText(notification) {
- return notification.content;
+ const text = await getNotificationTextContent(notification);
+ return text;
},
- getHtml(notification) {
+ async getHtml(notification) {
- return `<p>${notification.content}</p>`;
+ const html = await getNotificationHtmlContent(notification);
+ return html;
},
});
},
});
},
});
BackendFeature contract change.package.json.package.json.esm issue and config readingesm issue and config reading