diff --git a/plugins/techdocs-common/report.api.md b/plugins/techdocs-common/report.api.md index c7e1829a28..56a86778a8 100644 --- a/plugins/techdocs-common/report.api.md +++ b/plugins/techdocs-common/report.api.md @@ -8,4 +8,8 @@ export const TECHDOCS_ANNOTATION = 'backstage.io/techdocs-ref'; // @public (undocumented) export const TECHDOCS_EXTERNAL_ANNOTATION = 'backstage.io/techdocs-entity'; + +// @public (undocumented) +export const TECHDOCS_EXTERNAL_PATH_ANNOTATION = + 'backstage.io/techdocs-entity-path'; ``` diff --git a/plugins/techdocs-react/report.api.md b/plugins/techdocs-react/report.api.md index 23a9c9faaf..fd8de5803f 100644 --- a/plugins/techdocs-react/report.api.md +++ b/plugins/techdocs-react/report.api.md @@ -15,8 +15,15 @@ import { JSX as JSX_2 } from 'react/jsx-runtime'; import { MemoExoticComponent } from 'react'; import { PropsWithChildren } from 'react'; import { ReactNode } from 'react'; +import { RouteFunc } from '@backstage/core-plugin-api'; import { SetStateAction } from 'react'; +// @public +export const buildTechDocsURL: ( + entity: Entity, + routeFunc: TechDocsRouteFunc | undefined, +) => string | undefined; + // @public export function createTechDocsAddonExtension( options: TechDocsAddonOptions, @@ -27,6 +34,9 @@ export function createTechDocsAddonExtension( options: TechDocsAddonOptions, ): Extension<(props: TComponentProps) => JSX.Element | null>; +// @public +export function getEntityRootTechDocsPath(entity: Entity): string; + // @public export const SHADOW_DOM_STYLE_LOAD_EVENT = 'TECH_DOCS_SHADOW_DOM_STYLE_LOAD'; @@ -122,6 +132,13 @@ export type TechDocsReaderPageValue = { onReady?: () => void; }; +// @public +export type TechDocsRouteFunc = RouteFunc<{ + namespace: string; + kind: string; + name: string; +}>; + // @public export const TechDocsShadowDom: ( props: TechDocsShadowDomProps, diff --git a/plugins/techdocs-react/src/helpers.ts b/plugins/techdocs-react/src/helpers.ts index 8e3a6b5e7d..7c3ca71553 100644 --- a/plugins/techdocs-react/src/helpers.ts +++ b/plugins/techdocs-react/src/helpers.ts @@ -27,6 +27,12 @@ import { } from '@backstage/plugin-techdocs-common'; import { RouteFunc } from '@backstage/core-plugin-api'; +/** + * The RouteFunc used by buildTechDocsURL() to build the TechDocs link for + * an entity. + * + * @public + */ export type TechDocsRouteFunc = RouteFunc<{ namespace: string; kind: string; @@ -52,6 +58,11 @@ export function toLowercaseEntityRefMaybe( return entityRef; } +/** + * Get the entity path annotation from the given entity and ensure it starts with a slash. + * + * @public + */ export function getEntityRootTechDocsPath(entity: Entity): string { let path = entity.metadata.annotations?.[TECHDOCS_EXTERNAL_PATH_ANNOTATION]; if (!path) { @@ -63,6 +74,12 @@ export function getEntityRootTechDocsPath(entity: Entity): string { return path; } +/** + * Build the TechDocs URL for the given entity. This helper should be used anywhere there + * is a link to an entities TechDocs. + * + * @public + */ export const buildTechDocsURL = ( entity: Entity, routeFunc: TechDocsRouteFunc | undefined,