Show a README in a component page

Components already have a description field, however this is very limited in size (implicitly, how it is used) and used as a display name (compared to name, which is a more technically name). We want to provide some introduction sentences that tell what this component is about, without having the user to dive deep into the documentation (e.g. techdocs).

Feature Suggestion

We are looking for a way to provide a longer description of a component in the components details page. This is similar to a README in a GitHub repository. Compared to the description field, it shouldn’t have a (implicit) size limit and support formatting via markdown. The following screenshots illustrates the idea:

(From https://backstage.io/blog/2020/05/22/phase-2-service-catalog)

The screenshot contains tabs in the widget, I’m not sure what this means. It could either mean that multiple READMEs are linked, or that headlines are displayed as tabs instead. The later would be neat, no make it easier to stay in a small layout.

Possible Implementation

Right now we implement this using an annotation on our component entities, however we think this might be relevant for others too! There are two possible implementations we can imaging:

Based on GitHub

One way would be a complete client side implementation based on the GitHub API. With a linked GitHub repository, the frontend pulls the README.md from the repository root and displays it.

Based on the Catalog

While the GitHub solution is easy to implement, it is limited to GitHub and requires additional implementation for other SCM providers. Mono repositories may make such an implementation even more difficult. Maybe the data is not even part of the repository.

Therefore one could imaging, that the README content is part of the component entity, or a separate entity by itself. By storing it in the catalog we have more ingestion options (e.g. loading it via a location from the repository or a subfolder).

This could either be a feature of the catalog, or a separate plugin.

We can contribute an implementation, but would prefer to discuss a possible implementation first.

[dtuite]

We have a working README widget here which we will add to the sample app. It also handles top contributors, releases, languages used etc.

We’re going to rename the plugin to “Code insights” so there is room to incorporate GitLab, Bitbucket and whatever else in the future.

We will reference this issue when we submit the PR.

The screenshot shows a tab view but these are all standalone widgets which work just as well on the overview if desired.

/cc @lewtakm

[ArveSystad]

I might be too late here, but I tried to add the Roadie-made plugin, and it seems like it’ll end up prompting users to log into GitHub. We’ve set up Azure AD as our auth for Backstage (and don’t want to log in again with Github), so it seems a bit cumbersome. Since the Backstage backend already has access to the repos through the Backstage App, some sort of support for using that instead would be nice. It’d definitely also improve the immediate “Oh, this is useful”-factor after initial setup for many, I believe, since a lot of people use the Readme.md for basic descriptiopns/instructions for all their stuff.