diff --git a/.changeset/techdocs-hold-me-closer.md b/.changeset/techdocs-hold-me-closer.md index 2295603388..04bbf5088f 100644 --- a/.changeset/techdocs-hold-me-closer.md +++ b/.changeset/techdocs-hold-me-closer.md @@ -1,5 +1,7 @@ --- -'@backstage/plugin-techdocs-addons': minor +'@backstage/techdocs-addons': minor --- -Introducing an addon framework for TechDocs. +Introducing `@backstage/techdocs-addons`, a web library you can use to create TechDocs addons. + +Note: this package is not necessarily stable yet. After iteration on this package, its stability will be signaled by a major-version bump. diff --git a/.changeset/techdocs-swift-apricots-learn.md b/.changeset/techdocs-swift-apricots-learn.md deleted file mode 100644 index 70d21b3535..0000000000 --- a/.changeset/techdocs-swift-apricots-learn.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/plugin-techdocs-addons': patch ---- - -Separation between contexts and hooks diff --git a/.changeset/techdocs-until-you-puke.md b/.changeset/techdocs-until-you-puke.md index af70fe315b..74578b1067 100644 --- a/.changeset/techdocs-until-you-puke.md +++ b/.changeset/techdocs-until-you-puke.md @@ -2,15 +2,14 @@ '@backstage/plugin-techdocs': minor --- -TechDocs now supports a new method of customization: addons! +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: ```diff import { TechDocsIndexPage, TechDocsReaderPage } from '@backstage/plugin-techdocs'; -+ import { TechDocsAddons } from '@backstage/plugin-techdocs-addons'; ++ import { TechDocsAddons } from '@backstage/techdocs-addons'; + import { SomeAddon } from '@backstage/plugin-some-plugin'; -- import { techDocsPage } from './components/techdocs/TechDocsPage'; // ... @@ -19,7 +18,6 @@ import { TechDocsIndexPage, TechDocsReaderPage } from '@backstage/plugin-techdoc path="/docs/:namespace/:kind/:name/*" element={} > -- {techDocsPage} + + + @@ -32,7 +30,7 @@ To customize the TechDocs reader experience on the Catalog entity page, update y ```diff import { EntityTechdocsContent } from '@backstage/plugin-techdocs'; -+ import { TechDocsAddons } from '@backstage/plugin-techdocs-addons'; ++ import { TechDocsAddons } from '@backstage/techdocs-addons'; + import { SomeAddon } from '@backstage/plugin-some-plugin'; // ... diff --git a/packages/techdocs-addons/api-report.md b/packages/techdocs-addons/api-report.md index 4d5eef5edb..573361e5a7 100644 --- a/packages/techdocs-addons/api-report.md +++ b/packages/techdocs-addons/api-report.md @@ -3,23 +3,19 @@ > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). ```ts -import { AsyncState } from 'react-use/lib/useAsyncFn'; import { ComponentType } from 'react'; import { Extension } from '@backstage/core-plugin-api'; import { default as React_2 } from 'react'; -// @public +// @alpha export function createTechDocsAddon( options: TechDocsAddonOptions, ): Extension>; -// @public +// @alpha export const TECHDOCS_ADDONS_WRAPPER_KEY = 'techdocs.addons.wrapper.v1'; -// @public -export type TechDocsAddonAsyncMetadata = AsyncState; - -// @public +// @alpha export enum TechDocsAddonLocations { CONTENT = 'content', HEADER = 'header', @@ -28,17 +24,17 @@ export enum TechDocsAddonLocations { SUBHEADER = 'subheader', } -// @public +// @alpha export type TechDocsAddonOptions = { name: string; location: TechDocsAddonLocations; component: ComponentType; }; -// @public +// @alpha export const TechDocsAddons: React_2.ComponentType; -// @public +// @alpha export const useTechDocsAddons: () => { renderComponentByName: (name: string) => React_2.ReactElement< { diff --git a/packages/techdocs-addons/package.json b/packages/techdocs-addons/package.json index c8ed12ec8b..5635c9c6fe 100644 --- a/packages/techdocs-addons/package.json +++ b/packages/techdocs-addons/package.json @@ -42,8 +42,7 @@ "@material-ui/styles": "^4.11.0", "jss": "~10.8.2", "react-helmet": "6.1.0", - "react-router-dom": "6.0.0-beta.0", - "react-use": "^17.2.4" + "react-router-dom": "6.0.0-beta.0" }, "peerDependencies": { "@types/react": "^16.13.1 || ^17.0.0", diff --git a/packages/techdocs-addons/src/addons.tsx b/packages/techdocs-addons/src/addons.tsx index 60fe13bfeb..8304319a88 100644 --- a/packages/techdocs-addons/src/addons.tsx +++ b/packages/techdocs-addons/src/addons.tsx @@ -31,13 +31,13 @@ export const TECHDOCS_ADDONS_KEY = 'techdocs.addons.addon.v1'; /** * Marks the registry component. - * @public + * @alpha */ export const TECHDOCS_ADDONS_WRAPPER_KEY = 'techdocs.addons.wrapper.v1'; /** * TechDocs Addon registry. - * @public + * @alpha */ export const TechDocsAddons: React.ComponentType = () => null; @@ -49,7 +49,7 @@ const getDataKeyByName = (name: string) => { /** * Create a TechDocs addon. - * @public + * @alpha */ export function createTechDocsAddon( options: TechDocsAddonOptions, @@ -93,7 +93,7 @@ const getAllTechDocsAddonsData = (collection: ElementCollection) => { /** * hook to use addons in components - * @public + * @alpha */ export const useTechDocsAddons = () => { const node = useOutlet(); diff --git a/packages/techdocs-addons/src/index.ts b/packages/techdocs-addons/src/index.ts index 2ef7265db3..240f7ffb6a 100644 --- a/packages/techdocs-addons/src/index.ts +++ b/packages/techdocs-addons/src/index.ts @@ -27,4 +27,4 @@ export { TECHDOCS_ADDONS_WRAPPER_KEY, } from './addons'; export { TechDocsAddonLocations } from './types'; -export type { TechDocsAddonAsyncMetadata, TechDocsAddonOptions } from './types'; +export type { TechDocsAddonOptions } from './types'; diff --git a/packages/techdocs-addons/src/types.ts b/packages/techdocs-addons/src/types.ts index aa0d128427..9775e9a10e 100644 --- a/packages/techdocs-addons/src/types.ts +++ b/packages/techdocs-addons/src/types.ts @@ -15,11 +15,10 @@ */ import { ComponentType } from 'react'; -import { AsyncState } from 'react-use/lib/useAsyncFn'; /** * Locations for which TechDocs addons may be declared and rendered. - * @public + * @alpha */ export enum TechDocsAddonLocations { /** @@ -79,16 +78,10 @@ export enum TechDocsAddonLocations { /** * Options for creating a TechDocs addon. - * @public + * @alpha */ export type TechDocsAddonOptions = { name: string; location: TechDocsAddonLocations; component: ComponentType; }; - -/** - * Common response envelope for addon-related hooks. - * @public - */ -export type TechDocsAddonAsyncMetadata = AsyncState;