diff --git a/.changeset/warm-masks-ring.md b/.changeset/warm-masks-ring.md new file mode 100644 index 0000000000..9d1d5e0c5a --- /dev/null +++ b/.changeset/warm-masks-ring.md @@ -0,0 +1,85 @@ +--- +'@backstage/plugin-techdocs': patch +--- + +Add optional props to `TechDocCustomHome` to allow for more flexibility: + +```tsx +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: { showHeader: false, hideSupport: true }, + filterPredicate: entity => + entity?.metadata?.tags?.includes('golden-path') ?? false, + }, + { + title: 'Recommended', + description: 'Useful documentation', + panelType: 'InfoCardGrid', + panelProps: { + showHeader: false, + hideSupport: true, + 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: { showHeader: false, hideSupport: true, options: options }, + }, + ], + }, +]; + +const AppRoutes = () => { + + + } + /> + ; +}; +``` + +Add new Grid option called `InfoCardGrid` which is a more customizable card option for the Docs grid. + +```tsx + entity.metadata['external-docs']} +/> +``` + +Expose existing `CustomDocsPanel` so that it can be used independently if desired. diff --git a/docs/features/techdocs/how-to-guides.md b/docs/features/techdocs/how-to-guides.md index f8be6c9dd5..6bb4383674 100644 --- a/docs/features/techdocs/how-to-guides.md +++ b/docs/features/techdocs/how-to-guides.md @@ -137,6 +137,10 @@ Modify your `App.tsx` as follows: 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', @@ -145,18 +149,53 @@ const techDocsTabsConfig = [ title: 'Golden Path', description: 'Documentation about standards to follow', panelType: 'DocsCardGrid', + panelProps: { showHeader: false, hideSupport: true }, + filterPredicate: entity => + entity?.metadata?.tags?.includes('golden-path') ?? false, + }, + { + title: 'Recommended', + description: 'Useful documentation', + panelType: 'InfoCardGrid', + panelProps: { + showHeader: false, + hideSupport: true, + 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: { showHeader: false, hideSupport: true, options: options }, + }, + ], + }, ]; const AppRoutes = () => { } + element={ + + } /> ; }; diff --git a/plugins/techdocs/report.api.md b/plugins/techdocs/report.api.md index 04fd8dda39..ea7a1d7ea1 100644 --- a/plugins/techdocs/report.api.md +++ b/plugins/techdocs/report.api.md @@ -52,6 +52,17 @@ export type ContentStateTypes = /** There is only the latest and greatest content */ | 'CONTENT_FRESH'; +// @public +export const CustomDocsPanel: ({ + config, + entities, + index, +}: { + config: PanelConfig; + entities: Entity[]; + index: number; +}) => React_2.JSX.Element; + // @public export const DefaultTechDocsHome: ( props: TechDocsIndexPageProps, @@ -207,7 +218,7 @@ export type InfoCardGridClassKey = 'linkSpacer' | 'readMoreLink'; export type InfoCardGridProps = { entities: Entity[] | undefined; linkContent?: string | JSX.Element; - linkDest?: (entity: Entity) => string; + linkDestination?: (entity: Entity) => string; }; // @public diff --git a/plugins/techdocs/src/home/components/Grids/InfoCardGrid.tsx b/plugins/techdocs/src/home/components/Grids/InfoCardGrid.tsx index 7a96c2af4c..3503194bc4 100644 --- a/plugins/techdocs/src/home/components/Grids/InfoCardGrid.tsx +++ b/plugins/techdocs/src/home/components/Grids/InfoCardGrid.tsx @@ -45,7 +45,7 @@ const useStyles = makeStyles( export type InfoCardGridProps = { entities: Entity[] | undefined; linkContent?: string | JSX.Element; - linkDest?: (entity: Entity) => string; + linkDestination?: (entity: Entity) => string; }; /** @@ -54,13 +54,13 @@ export type InfoCardGridProps = { * @public */ export const InfoCardGrid = (props: InfoCardGridProps) => { - const { entities, linkContent, linkDest } = props; + const { entities, linkContent, linkDestination } = props; const classes = useStyles(); const getRouteToReaderPageFor = useRouteRef(rootDocsRouteRef); const config = useApi(configApiRef); - const linkDestination = (entity: Entity) => - typeof linkDest === 'function' - ? linkDest(entity) + const linkRoute = (entity: Entity) => + typeof linkDestination === 'function' + ? linkDestination(entity) : getRouteToReaderPageFor({ namespace: toLowerMaybe( entity.metadata.namespace ?? 'default', @@ -84,7 +84,7 @@ export const InfoCardGrid = (props: InfoCardGridProps) => {
{entity?.metadata?.description}
diff --git a/plugins/techdocs/src/home/components/TechDocsCustomHome.tsx b/plugins/techdocs/src/home/components/TechDocsCustomHome.tsx index 781d4b337c..b939d75893 100644 --- a/plugins/techdocs/src/home/components/TechDocsCustomHome.tsx +++ b/plugins/techdocs/src/home/components/TechDocsCustomHome.tsx @@ -92,7 +92,12 @@ export interface TabConfig { */ export type TabsConfig = TabConfig[]; -const CustomPanel = ({ +/** + * Component which can be used to render entities in a custom way. + * + * @public + */ +export const CustomDocsPanel = ({ config, entities, index, @@ -241,7 +246,7 @@ export const TechDocsCustomHome = (props: TechDocsCustomHomeProps) => { /> {currentTabConfig.panels.map((config, index) => ( -