Support an annotation that skips building techdocs

Feature Suggestion

We’d like it to be possible to define the following catalog-info.yaml

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-component-with-docs
  description: My awesome component
  annotations:
    backstage.io/techdocs-ref: dir:.
    my-org.com/skip-techdocs-build: true
spec:
...

Adding the annotation my-org.com/skip-techdocs-build (potentially customizable in config) with the value true would cause the techdocs backend to not attempt to build techdocs for this component. However techdocs would still be fetched from whatever datastore is in use, and the docs for this component would still be displayed in the UI. This would allow users to place their own tech-docs in the correct place and have them served. See the context below for more info on the use case.

Possible Implementation

Can we add an additional condition to this line? https://github.com/backstage/backstage/blob/9c17a6cdb9be6ba85ef9bfab76b94e672902b9fe/plugins/techdocs-backend/src/service/router.ts#L203

Something like

if (config.getString('techdocs.builder') !== 'local' || entity?.metadata?.annotations?.[config.getString('techdocs.builder.ignoreAnnotation'))

I’m happy to have a go at implementing this, or an alternate solution.

Context

At our organisation, we’d like to support a ‘hybrid’ approach to handling the building of tech docs.

One path would be the ‘default’/‘out of the box’ experience, where the Backstage backend builds the docs for you. The advantage here is that users need only populate their repository with their docs and an mkdocs.yaml, and we do the rest for them. For many users, this would work well. The limitation is that the user is bound by the plugins we choose to offer, and other things related to the execution of mkdocs.

We’d like users to have the option of opting out of us building docs for them, if they need added flexibility in how they build their docs, or to customize mkdocs plugins etc. We think a sensible way for them to signal this would be to add an annotation to their catalog-info.yaml that indicates that we should not build the docs for them. They would instead build the docs themselves, and write them to the appropriate place for Backstage to serve them from.

If there’s a better/easier way to accomplish this, we’d love to hear!

[kuangp]

related: https://github.com/backstage/backstage/issues/5905

[Niksko]

@soapraj yep, closing!