From a4f863f8f859b19e4010a5833e1883fb8bbbdb62 Mon Sep 17 00:00:00 2001 From: James Turley Date: Thu, 18 Feb 2021 14:27:09 +0000 Subject: [PATCH] Document browser URL annotations --- .github/styles/vocab.txt | 1 + .../well-known-annotations.md | 19 +++++++++++++++++++ 2 files changed, 20 insertions(+) diff --git a/.github/styles/vocab.txt b/.github/styles/vocab.txt index 41ec95e9aa..2a8854b8a2 100644 --- a/.github/styles/vocab.txt +++ b/.github/styles/vocab.txt @@ -166,6 +166,7 @@ interop jq js json +jsonnet jsx kubectl kubernetes diff --git a/docs/features/software-catalog/well-known-annotations.md b/docs/features/software-catalog/well-known-annotations.md index 2cbb829554..795bf15621 100644 --- a/docs/features/software-catalog/well-known-annotations.md +++ b/docs/features/software-catalog/well-known-annotations.md @@ -70,6 +70,25 @@ The value of this annotation is a location reference string (see above). If this annotation is specified, it is expected to point to a repository that the TechDocs system can read and generate docs from. +### backstage.io/browser-view-url, backstage.io/browser-edit-url, backstage.io/browser-source-url + +```yaml +# Example: +metadata: + annotations: + backstage.io/browser-view-url: https://some.website/catalog-info.yaml + backstage.io/browser-edit-url: https://github.com/my-org/catalog/edit/master/my-service.jsonnet + backstage.io/browser-source-url: https://github.com/my-org/my-service +``` + +These annotations allow customising links from the catalog pages. The view URL +should point to the canonical metadata YAML that governs this entity. The edit +URL should point to the source file for the metadata. The source URL should +point to the source code of the entity itself (where relevant, i.e. when the +entity is a `Component`). In the example above, `my-org` generates its catalog +data from Jsonnet files in a monorepo, and so for the `my-service` component, we +need three custom links. + ### jenkins.io/github-folder ```yaml