Add Backstage Plugin Gallery

Add a plugin gallery to `/backstage/plugins` which lists Rollbar and
Sentry (just to get started). Clicking each plugin brings the user to a
page which explains how to install and configure the plugin. The
plugins are described as a combination of YAML file and a MD file
which has arbitrary notes about the plugin.

 - Add logos into `content/assets`.
 - add a custom YAML transfomer plugin for loading plugins YAMLs and
   replacing image filesystem paths with sharp image objects.
 - Abstract some components to make them useful on this new page.

.babelrc

@@ -0,0 +1,8 @@
+{
+  "presets": ["babel-preset-gatsby"],
+  "plugins": [
+    ["prismjs", {
+      "languages": ["javascript", "css", "bash", "typescript"],
+    }]
+  ]
+}

content/blog/backstage-docker-compose/index.md

@@ -1,7 +1,7 @@
 ---
 title: Running Backstage with Docker Compose
 date: '2020-05-25T21:00:00.0Z'
-description: Docker Compose is a handly way to run Backstage for development or light use. Here's a setup which will get you started with Backstage quickly.
+description: Docker Compose is an easy way to run Backstage for development or light use. Here's a setup which will get you started with Backstage quickly.
 ---
 
 To run Backstage and the Lighthouse plugin with Docker Compose we need three things

content/blog/backstage-lighthouse-plugin/index.md

@@ -105,7 +105,7 @@ export { plugin as LighthousePlugin } from '@backstage/plugin-lighthouse';
 
 In `packages/app/src/apis.ts` you should see that the Lighthouse plugin is configured to send requests to port `3003`.
 
-```type
+```typescript
 builder.add(lighthouseApiRef, new LighthouseRestApi('http://localhost:3003'));
 ```
 

content/plugins/descriptions/rollbar.yaml

@@ -0,0 +1,53 @@
+name: rollbar
+heading: 'Backstage Rollbar Plugin'
+lead: 'Correlate services with problems in production'
+
+seo:
+  title: 'Backstage Rollbar Plugin | Roadie'
+  description: |
+    The Backstage Rollbar plugin shows you errors which are affecting
+    your production services, directly inside Backstage.
+
+logo:
+  fileSystemPath: './content/assets/logos/rollbar/logo-white-120x21.png'
+  width: 120
+  height: 21
+
+coverImage:
+  fileSystemPath: './content/assets/rollbar-plugin-1550x715.png'
+  alt: 'A screenshot of the Rollbar plugin. It is showing a list of errors.'
+
+gettingStarted:
+  - intro: |
+      Ensure you have the Rollbar Backend plugin installed. See the notes below to learn how
+      to add a Rollbar API token to Backstage.
+  - intro: 'Install the plugin in your Backstage instance'
+    language: 'bash'
+    code: 'yarn add @backstage/plugin-rollbar'
+  - intro: 'Add the plugin to the list of plugins'
+    language: 'typescript'
+    code: |
+      // packages/app/src/plugins.ts
+      export { plugin as Rollbar } from '@backstage/plugin-rollbar';
+  - intro: 'Add the plugin API to your Backstage instance.'
+    language: 'typescript'
+    code: |
+      // packages/app/src/api.ts
+      import { RollbarClient, rollbarApiRef } from '@backstage/plugin-rollbar';
+
+      // ...
+
+      builder.add(
+        rollbarApiRef,
+        new RollbarClient({
+          apiOrigin: backendUrl,
+          basePath: '/rollbar',
+        }),
+      );
+
+      // Alternatively you can use the mock client
+      // builder.add(rollbarApiRef, new RollbarMockClient());
+
+style:
+  primaryColor: '#104c91'
+  contrastingColor: '#fff'

content/plugins/descriptions/sentry.yaml

@@ -0,0 +1,35 @@
+name: sentry
+heading: 'Backstage Sentry Plugin'
+lead: 'Correlate services with problems in production'
+
+seo:
+  title: 'Backstage Sentry Plugin | Roadie'
+  description: |
+    The Backstage Sentry plugin alerts you to errors which are affecting
+    your production services, directly inside Backstage.
+
+logo:
+  fileSystemPath: './content/assets/logos/sentry/sentry-glyph-light-200x184.png'
+  width: 200
+  height: 184
+
+coverImage:
+  fileSystemPath: './content/assets/sentry-plugin-1604x716.png'
+  alt: 'A screenshot of the Sentry plugin. It is showing a list of errors.'
+
+gettingStarted:
+  - intro: |
+      Ensure you have the Sentry Backend plugin installed. See the notes below to learn how
+      to add a Sentry API token to Backstage.
+  - intro: 'Install the plugin in your Backstage instance'
+    language: 'bash'
+    code: 'yarn add @backstage/plugin-sentry'
+  - intro: 'Add the plugin to the list of plugins'
+    language: 'typescript'
+    code: |
+      // packages/app/src/plugins.ts
+      export { plugin as Sentry } from '@backstage/plugin-sentry';
+
+style:
+  primaryColor: '#310f32'
+  contrastingColor: '#fff'

content/plugins/descriptions/template.yaml

@@ -0,0 +1,48 @@
+# The server must be restarted to pick up changes in ths file.
+
+# Required. Must be unique across all files in the directory.
+name: template
+heading: 'Backstage Template Plugin'
+# Keep it short
+lead: 'Describe the problem that the plugin will solve for users'
+
+seo:
+  # Don't forget to end with "| Roadie"
+  title: 'Backstage Template Plugin | Roadie'
+  description: |
+    What would you want to know before clicking this in Google. Think about searcher intent.
+    Don't forget to keep it under 160 chars.
+
+logo:
+  # This must be a relative path. It should start without a slash or with ./
+  fileSystemPath: './content/assets/logos/sentry/sentry-glyph-light-200x184.png'
+  # The dimensions are required.
+  width: 200
+  height: 184
+
+coverImage:
+  # This must be a relative path. It should start without a slash or with ./
+  fileSystemPath: './content/assets/sentry-plugin-1604x716.png'
+  alt: 'Explain what is in the image'
+
+# Instructions for someone who wants to use this plugin.
+# languages used here must be listed in the .babelrc
+gettingStarted:
+    # What will this step accomplish?
+  - intro: 'Install the plugin'
+    language: 'bash'
+    code: 'yarn add @backstage/plugin-template'
+  - intro: 'Import it into your Backstage application'
+    language: 'typescript'
+    code: ""
+  - intro: 'Heres where things get good...'
+    language: 'typescript'
+    code: |
+      // packages/app/src/plugins.ts
+      export { plugin as Template } from '@backstage/plugin-template';
+
+# Optional. Use this to suit the brand of the tool that the plugin integrates with.
+style:
+  # These colors will fall back to a default if omitted.
+  primaryColor: 'hsl(30.6, 97.1%, 58.8%)'
+  contrastingColor: '#fff'

content/plugins/notes/rollbar.md

@@ -0,0 +1,14 @@
+---
+name: rollbar
+---
+
+At the time of writing, in July 2020, Rollbar are rolling out a new UI which doesn't seem to
+have the ability to create API keys.
+
+To switch back to the old UI temporarily, click your organization's name in the bottom left
+corner and select "Switch to old UI".
+
+Once there, go to your Account settings and click Account access tokens in the sidebar. Here
+you can "Add new access token". Make sure it has the `read` scope.
+
+![Rollbar access token page](./rollbar-accounts-access-tokens-1590x1397.png)

content/plugins/notes/sentry.md

@@ -0,0 +1,21 @@
+---
+name: sentry
+---
+
+The Backstage backend must have access to a `SENTRY_TOKEN` API key environment variable.
+
+To get an API key, first create an internal application in the Sentry UI. Do this at the
+organization level, rather than the personal level.
+
+Give your application a name and a Webhook URL, then be sure to give the ability to read
+issues and projects. These will be displayed in Backstage so it's important that the plugin
+can access them.
+
+![Creating an internal application in the Sentry UI](./sentry-create-internal-application-1590x1621.png)
+
+Once you have an internal application, you can create a token. Run the Backstage backend with
+this token.
+
+```bash
+env SENTRY_TOKEN=123abc yarn start
+```

content/plugins/notes/template.md

@@ -0,0 +1,5 @@
+---
+name: template
+---
+
+The Backstage backend must have access to a `SENTRY_TOKEN` environment variable. The

gatsby-config.js

@@ -1,9 +1,13 @@
 const fs = require('fs');
+var { minify } = require('html-minifier');
+const camelCase = require('lodash/camelCase');
 
 const theme = require('./src/theme');
 
-const termsAndConditionsText = fs.readFileSync('./raw-html/termsAndConditionsText.html').toString();
-const privacyPolicyText = fs.readFileSync('./raw-html/privacyPolicyText.html').toString();
+const loadHtml = (path) => minify(fs.readFileSync(path).toString());
+
+const termsAndConditionsText = loadHtml('./manual-loaded-content/termsAndConditionsText.html');
+const privacyPolicyText = loadHtml('./manual-loaded-content/privacyPolicyText.html');
 
 const SITE_TITLE = 'Roadie';
 
@@ -29,15 +33,35 @@ module.exports = {
       options: {
         path: `${__dirname}/content`,
         name: `blog`,
+        // Ignore stuff like Vim swp files, .DS_Store etc.
+        ignore: ['**/.*'],
       },
     },
     {
       resolve: `gatsby-source-filesystem`,
       options: {
         path: `${__dirname}/content/assets`,
         name: `assets`,
+        ignore: ['**/.*'],
+      },
+    },
+    {
+      resolve: `gatsby-source-filesystem`,
+      options: {
+        path: `${__dirname}/content/plugins/descriptions`,
+        name: `pluginDescriptions`,
+        ignore: ['**/template*', '**/.*'],
+      },
+    },
+    {
+      resolve: `gatsby-source-filesystem`,
+      options: {
+        path: `${__dirname}/content/plugins/notes`,
+        name: `pluginNotes`,
+        ignore: ['**/template*', '**/.*'],
       },
     },
+
     {
       resolve: `gatsby-transformer-remark`,
       options: {
@@ -60,6 +84,16 @@ module.exports = {
         ],
       },
     },
+
+    {
+      resolve: 'gatsby-transformer-plugin-descriptions',
+      options: {
+        // Without this, the query would just be 'descriptionsYaml'. It's a bit too generic
+        // and likely to clash as the site gets more complex.
+        typeName: ({ node }) => `${camelCase(node.relativeDirectory)}Yaml`,
+      },
+    },
+
     `gatsby-transformer-sharp`,
     `gatsby-plugin-sharp`,
     {
@@ -68,15 +102,14 @@ module.exports = {
         trackingId: 'UA-166771003-3',
       },
     },
-    `gatsby-plugin-feed`,
     {
       resolve: `gatsby-plugin-manifest`,
       options: {
         name: SITE_TITLE,
         short_name: SITE_TITLE,
         start_url: `/`,
         background_color: `#ffffff`,
-        theme_color: `#663399`,
+        theme_color: theme.palette.primary.main,
         display: `minimal-ui`,
         icon: `content/assets/roadie-r-764x764.png`,
       },