diff --git a/.changeset/modern-trees-add.md b/.changeset/modern-trees-add.md index 64b36c3adb..bb5ea78a5b 100644 --- a/.changeset/modern-trees-add.md +++ b/.changeset/modern-trees-add.md @@ -3,4 +3,4 @@ '@backstage/plugin-catalog': minor --- -This change allows a new annotation of `backstage.io/techdocs-external-ref` 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-external-ref: 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. +This change allows a new annotation of `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. diff --git a/docs/features/software-catalog/well-known-annotations.md b/docs/features/software-catalog/well-known-annotations.md index 651520cd28..70f5ff5e14 100644 --- a/docs/features/software-catalog/well-known-annotations.md +++ b/docs/features/software-catalog/well-known-annotations.md @@ -100,13 +100,13 @@ alongside the entity's source code, the value of this annotation can point to an absolute URL, matching the location reference string format outlined above, for example: `url:https://github.com/backstage/backstage/tree/master` -### backstage.io/techdocs-ref +### backstage.io/techdocs-entity ```yaml # Example: metadata: annotations: - backstage.io/techdocs-external-ref: component:default/example + backstage.io/techdocs-entity: component:default/example ``` The value of this annotation informs of an external entity that owns the TechDocs. diff --git a/docs/features/techdocs/how-to-guides.md b/docs/features/techdocs/how-to-guides.md index 0ab89ed9b6..1eaaa02c6d 100644 --- a/docs/features/techdocs/how-to-guides.md +++ b/docs/features/techdocs/how-to-guides.md @@ -683,7 +683,7 @@ documentation to the appropriate location in the TechDocs external storage. In systems where you might have multiple entities for example a System with a Website and an API, when served from a Monorepo you might want to keep the TechDocs in one location in the repository. -In this case you can add the `backstage.io/techdocs-external-ref` annotation and point to the owners `entityRef` and use its TechDocs. This allows the Subcomponents to read the parents docs, filling the TechDocs link on the `AboutCard` element and the Techdocs tab +In this case you can add the `backstage.io/techdocs-entity` annotation and point to the owners `entityRef` and use its TechDocs. This allows the Subcomponents to read the parents docs, filling the TechDocs link on the `AboutCard` element and the Techdocs tab ```yaml apiVersion: backstage.io/v1alpha1 @@ -705,5 +705,5 @@ metadata: namespace: default description: This is the child entity annotations: - backstage.io/techdocs-external-ref: system:default/example + backstage.io/techdocs-entity: system:default/example ``` diff --git a/plugins/catalog/src/components/AboutCard/AboutCard.test.tsx b/plugins/catalog/src/components/AboutCard/AboutCard.test.tsx index 036507ada7..1679e2ddf5 100644 --- a/plugins/catalog/src/components/AboutCard/AboutCard.test.tsx +++ b/plugins/catalog/src/components/AboutCard/AboutCard.test.tsx @@ -355,7 +355,7 @@ describe('', () => { metadata: { name: 'software', annotations: { - 'backstage.io/techdocs-external-ref': 'system:default/example', + 'backstage.io/techdocs-entity': 'system:default/example', }, }, spec: { diff --git a/plugins/catalog/src/components/AboutCard/AboutCard.tsx b/plugins/catalog/src/components/AboutCard/AboutCard.tsx index 6c28660144..6a782cffc1 100644 --- a/plugins/catalog/src/components/AboutCard/AboutCard.tsx +++ b/plugins/catalog/src/components/AboutCard/AboutCard.tsx @@ -114,10 +114,10 @@ export function AboutCard(props: AboutCardProps) { let techdocsRef: CompoundEntityRef | undefined; - if (entity.metadata.annotations?.['backstage.io/techdocs-external-ref']) { + if (entity.metadata.annotations?.['backstage.io/techdocs-entity']) { try { techdocsRef = parseEntityRef( - entity.metadata.annotations?.['backstage.io/techdocs-external-ref'], + entity.metadata.annotations?.['backstage.io/techdocs-entity'], ); // not a fan of this but we don't care if the parseEntityRef fails } catch { @@ -136,7 +136,7 @@ export function AboutCard(props: AboutCardProps) { disabled: !( entity.metadata.annotations?.['backstage.io/techdocs-ref'] || - entity.metadata.annotations?.['backstage.io/techdocs-external-ref'] + entity.metadata.annotations?.['backstage.io/techdocs-entity'] ) || !viewTechdocLink, icon: , href: diff --git a/plugins/techdocs/src/EntityPageDocs.tsx b/plugins/techdocs/src/EntityPageDocs.tsx index 56c1341aa2..3d9aced9f3 100644 --- a/plugins/techdocs/src/EntityPageDocs.tsx +++ b/plugins/techdocs/src/EntityPageDocs.tsx @@ -30,10 +30,10 @@ type EntityPageDocsProps = { entity: Entity }; export const EntityPageDocs = ({ entity }: EntityPageDocsProps) => { let entityRef = getCompoundEntityRef(entity); - if (entity.metadata.annotations?.['backstage.io/techdocs-external-ref']) { + if (entity.metadata.annotations?.['backstage.io/techdocs-entity']) { try { entityRef = parseEntityRef( - entity.metadata.annotations?.['backstage.io/techdocs-external-ref'], + entity.metadata.annotations?.['backstage.io/techdocs-entity'], ); } catch { // not a fan of this but we don't care if the parseEntityRef fails diff --git a/plugins/techdocs/src/Router.tsx b/plugins/techdocs/src/Router.tsx index 5c967a54e8..3a0d2515d8 100644 --- a/plugins/techdocs/src/Router.tsx +++ b/plugins/techdocs/src/Router.tsx @@ -26,7 +26,7 @@ import { useEntity } from '@backstage/plugin-catalog-react'; const TECHDOCS_ANNOTATION = 'backstage.io/techdocs-ref'; -const TECHDOCS_EXTERNAL_ANNOTATION = 'backstage.io/techdocs-external-ref'; +const TECHDOCS_EXTERNAL_ANNOTATION = 'backstage.io/techdocs-entity'; /** * Helper that takes in entity and returns true/false if TechDocs is available for the entity