docs(homepage): add techdocs (#1674)

Signed-off-by: Christoph Jerolimov <jerolimov+git@redhat.com>

plugins/dynamic-home-page/catalog-info.yaml

@@ -0,0 +1,61 @@
+# https://backstage.io/docs/features/software-catalog/descriptor-format#kind-component
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: janus-idp-dynamic-home-page
+  title: Dynamic Home Page plugin
+  description: Home Page plugin based on the upstream home [page] plugin that can be extended via (dynamic) plugins.
+  annotations:
+    backstage.io/source-location: url:https://github.com/janus-idp/backstage-showcase/tree/main/plugins/dynamic-home-page
+    #backstage.io/source-location: file:../../plugins/dynamic-home-page/REQUIRED_TO_BUILD_THE_TECHDOCS_LOCALLY
+    backstage.io/view-url: https://github.com/janus-idp/backstage-showcase/blob/main/plugins/dynamic-home-page/catalog-info.yaml
+    backstage.io/edit-url: https://github.com/janus-idp/backstage-showcase/edit/main/plugins/dynamic-home-page/catalog-info.yaml
+    backstage.io/techdocs-ref: dir:.
+    github.com/project-slug: janus-idp/backstage-showcase
+    github.com/team-slug: janus-idp/maintainers-plugins
+    sonarqube.org/project-key: janus-idp_backstage-showcase
+  tags:
+    - homepage
+  links:
+    - url: https://github.com/janus-idp/backstage-showcase/tree/main/plugins/dynamic-home-page
+      title: GitHub Source
+      icon: source
+      type: source
+spec:
+  type: backstage-plugin
+  lifecycle: production
+  owner: rhdh-team
+  system: rhdh
+  subcomponentOf: janus-idp-backstage-plugins
+---
+# https://backstage.io/docs/features/software-catalog/descriptor-format#kind-component
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: janus-idp-dynamic-home-page-frontend
+  title: '@janus-idp/backstage-plugin-dynamic-home-page'
+  description: Home Page plugin based on the upstream home [page] plugin that can be extended via (dynamic) plugins.
+  annotations:
+    backstage.io/source-location: url:https://github.com/janus-idp/backstage-showcase/tree/main/plugins/dynamic-home-page
+    backstage.io/view-url: https://github.com/janus-idp/backstage-showcase/blob/main/plugins/dynamic-home-page/catalog-info.yaml
+    backstage.io/edit-url: https://github.com/janus-idp/backstage-showcase/edit/main/plugins/dynamic-home-page/catalog-info.yaml
+    backstage.io/techdocs-entity: component:janus-idp-dynamic-home-page
+    github.com/project-slug: janus-idp/backstage-showcase
+    github.com/team-slug: janus-idp/maintainers-plugins
+    sonarqube.org/project-key: janus-idp_backstage-showcase
+  tags:
+    - homepage
+  links:
+    - url: https://github.com/janus-idp/backstage-plugins/tree/main/plugins/dynamic-home-page
+      title: GitHub Source
+      icon: source
+      type: source
+spec:
+  type: backstage-frontend-plugin
+  lifecycle: production
+  owner: rhdh-team
+  system: rhdh
+  subcomponentOf: janus-idp-dynamic-home-page
+  dependsOn:
+    - component:backstage-plugin-home
+    - component:backstage-plugin-home-react

plugins/dynamic-home-page/docs/catalog-starred.md

@@ -0,0 +1,34 @@
+# Catalog starred entities
+
+Shows entities the user has starred in the catalog.
+
+![Home page with catalog starred entities card](catalog-starred.png)
+
+## Examples
+
+Starred entities and starred entities grouped by catalog `Kind`:
+
+```yaml
+dynamicPlugins:
+  frontend:
+    janus-idp.backstage-plugin-dynamic-home-page:
+      mountPoints:
+        - mountPoint: home.page/cards
+          importName: CatalogStarredEntitiesCard
+        - mountPoint: home.page/cards
+          importName: CatalogStarredEntitiesCard
+          config:
+            props:
+              groupByKind: true
+```
+
+## Available props
+
+| Prop                       | Default                                                        | Description                                                      |
+| -------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `noStarredEntitiesMessage` | "Click the star beside an entity name to add it to this list!" | Message that is shown when no entities are starred               |
+| `groupByKind`              | `false`                                                        | Option to enable a variant that group the elements by their kind |
+
+## Contributions
+
+The dynamic home page plugin reexports the [`HomePageStarredEntities`](https://github.com/backstage/backstage/tree/master/plugins/home/src/homePageComponents/StarredEntities) from the [home plugin](https://github.com/backstage/backstage/tree/master/plugins/home).

plugins/dynamic-home-page/docs/create-a-new-card.md

@@ -0,0 +1,53 @@
+# Create a new card
+
+Any plugin can add additional cards/content by exporting a react component.
+
+Cards commonly uses the [InfoCard](https://backstage.io/storybook/?path=/story/layout-information-card--default) component from `@backstage/core-components`.
+
+1. Create and export a new react component:
+
+   ```tsx
+   import React from 'react';
+
+   import { InfoCard, MarkdownContent } from '@backstage/core-components';
+
+   export interface MarkdownCardProps {
+     title?: string;
+     content?: string;
+   }
+
+   export const MarkdownCard = (props: MarkdownCardProps) => {
+     return (
+       <InfoCard title={props.title}>
+         <MarkdownContent dialect="gfm" content={props.content ?? ''} />
+       </InfoCard>
+     );
+   };
+   ```
+
+2. Export the card in your `plugin.ts`:
+
+   ```tsx
+   export const Markdown = dynamicHomePagePlugin.provide(
+     createComponentExtension({
+       name: 'Markdown',
+       component: {
+         lazy: () => import('./components/Markdown').then(m => m.Markdown),
+       },
+     }),
+   );
+   ```
+
+3. And finally, users can add them to their `app-config` to expose the component as mount point `home.page/cards`:
+
+   ```yaml
+   dynamicPlugins:
+     frontend:
+       your-plugin-id:
+         mountPoints:
+           - mountPoint: home.page/cards
+             importName: YourHomePageCard
+             config:
+               layout: ...
+               props: ...
+   ```

plugins/dynamic-home-page/docs/customization.md

@@ -0,0 +1,80 @@
+# Customization
+
+The dynamic home page allows admins to constomize the homepage in the `app-config`, and plugin authors to extend the home page with additional cards or content.
+
+Additional cards can automatically appear based on installed and enabled plugins.
+
+## Default home page
+
+The default home page shows a Search input field, a "Quick Access" card, and a "Your Starred Entities" card by default.
+
+![Default home page](default-homepage.png)
+
+The customization can happen in any loaded `app-config` from the `dynamicPlugins` section.
+
+The home page loads automatically a configuration like this, when no other configiration is passed:
+
+```yaml
+dynamicPlugins:
+  frontend:
+    janus-idp.backstage-plugin-dynamic-home-page:
+      dynamicRoutes:
+        - path: /
+          importName: DynamicHomePage
+      mountPoints:
+        - mountPoint: home.page/cards
+          importName: SearchBar
+          config:
+            layouts:
+              xl: { w: 10, h: 1, x: 1 }
+              lg: { w: 10, h: 1, x: 1 }
+              md: { w: 10, h: 1, x: 1 }
+              sm: { w: 10, h: 1, x: 1 }
+              xs: { w: 12, h: 1 }
+              xxs: { w: 12, h: 1 }
+        - mountPoint: home.page/cards
+          importName: QuickAccessCard
+          config:
+            layouts:
+              xl: { w: 7, h: 8 }
+              lg: { w: 7, h: 8 }
+              md: { w: 7, h: 8 }
+              sm: { w: 12, h: 8 }
+              xs: { w: 12, h: 8 }
+              xxs: { w: 12, h: 8 }
+        - mountPoint: home.page/cards
+          importName: CatalogStarredEntitiesCard
+          config:
+            layouts:
+              xl: { w: 5, h: 4, x: 7 }
+              lg: { w: 5, h: 4, x: 7 }
+              md: { w: 5, h: 4, x: 7 }
+              sm: { w: 12, h: 4 }
+              xs: { w: 12, h: 4 }
+              xxs: { w: 12, h: 4 }
+```
+
+## Adding cards from a plugin
+
+Plugins can add additional cards/content by exporting a react component.
+
+Each card can have a `layouts` definition and `props` that are depending on the used component like this:
+
+```yaml
+dynamicPlugins:
+  frontend:
+    janus-idp.backstage-plugin-dynamic-home-page:
+      mountPoints:
+        - mountPoint: home.page/cards
+          importName: Headline
+          config:
+            layouts:
+              xl: { h: 1 }
+              lg: { h: 1 }
+              md: { h: 1 }
+              sm: { h: 1 }
+              xs: { h: 1 }
+              xxs: { h: 1 }
+            props:
+              title: Important info
+```

plugins/dynamic-home-page/docs/featured-docs.md

@@ -0,0 +1,28 @@
+# Featured docs
+
+Shows some techdocs.
+
+![Home page with featured docs card](featured-docs.png)
+
+## Example
+
+```yaml
+dynamicPlugins:
+  frontend:
+    janus-idp.backstage-plugin-dynamic-home-page:
+      mountPoints:
+        - mountPoint: home.page/cards
+          importName: FeaturedDocsCard
+```
+
+## Available props
+
+| Prop            | Default      | Description                          |
+| --------------- | ------------ | ------------------------------------ |
+| `filter`        | none         | Catalog filter options               |
+| `responseLimit` | 10           | Number of entries that are displayed |
+| `subLinkText`   | `LEARN MORE` | Link text to open the docs           |
+
+## Contributions
+
+The dynamic home page plugin reexports the [`FeaturedDocsCard`](https://github.com/backstage/backstage/tree/master/plugins/home/src/homePageComponents/FeaturedDocsCard) from the [home plugin](https://github.com/backstage/backstage/tree/master/plugins/home).

plugins/dynamic-home-page/docs/headline.md

@@ -0,0 +1,32 @@
+# Headline
+
+Allow admins and customers to structure the home page content.
+
+![Home page with some headlines](headline.png)
+
+## Example
+
+```yaml
+dynamicPlugins:
+  frontend:
+    janus-idp.backstage-plugin-dynamic-home-page:
+      mountPoints:
+        - mountPoint: home.page/cards
+          importName: Headline
+          config:
+            layouts:
+              xl: { h: 1 }
+              lg: { h: 1 }
+              md: { h: 1 }
+              sm: { h: 1 }
+              xs: { h: 1 }
+              xxs: { h: 1 }
+            props:
+              title: Important info
+```
+
+## Available props
+
+| Prop    | Default | Description |
+| ------- | ------- | ----------- |
+| `title` | none    | Title       |

plugins/dynamic-home-page/docs/index.md

@@ -0,0 +1,11 @@
+# Dynamic home page
+
+The dynamic home page plugin is based on the upstream [home plugin](https://github.com/backstage/backstage/blob/master/plugins/home/README.md).
+
+It allows admins to constomize the homepage in the `app-config`, and plugin authors to extend the home page with additional cards or content.
+
+The default home page shows a Search input field, a "Quick Access" card, and a "Your Starred Entities" card by default.
+
+Additional cards can automatically appear based on installed and enabled plugins.
+
+![Default home page](default-homepage.png)

plugins/dynamic-home-page/docs/jokes.md

@@ -0,0 +1,22 @@
+# Jokes
+
+A card that shows a random joke loaded from [official-joke-api.appspot.com](https://official-joke-api.appspot.com/).
+
+The sourcecode and jokes of the Joke API are available on [GitHub](https://github.com/15Dkatz/official_joke_api).
+
+![Home page with a joke card](jokes.png)
+
+## Example
+
+```yaml
+dynamicPlugins:
+  frontend:
+    janus-idp.backstage-plugin-dynamic-home-page:
+      mountPoints:
+        - mountPoint: home.page/cards
+          importName: JokeCard
+```
+
+## Contributions
+
+The dynamic home page plugin reexports the [`HomePageRandomJoke`](https://github.com/backstage/backstage/tree/master/plugins/home/src/homePageComponents/RandomJoke) from the [home plugin](https://github.com/backstage/backstage/tree/master/plugins/home).