chore: add link checker workflow (#1779)

* chore: Add link checker workflow

Signed-off-by: Tomas Kral <[email protected]>

* chore: fix broken links

* fix(docs): broken links

* fix(docs): broken links

* chore(ci): simplify link-checker.yaml

* chore: fix links

* chore: link-checker, check only md files in root and in docs

* chore(docs): fix broken links

---------

Signed-off-by: Tomas Kral <[email protected]>

Author: kadel

.github/workflows/link-checker.config.json

@@ -0,0 +1,7 @@
+{
+  "ignorePatterns": [
+    { "pattern": "^http://localhost:7007" },
+    { "pattern": "^https://pkgs.devel.redhat.com" },
+    { "pattern": "^https://gitlab.cee.redhat.com" }
+  ]
+}

.github/workflows/link-checker.yaml

@@ -0,0 +1,27 @@
+name: Check Markdown links
+
+on:
+  pull_request:
+    paths:
+      - '**.md'
+      - 'docs/**'
+
+
+jobs:
+  markdown-link-check:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Check markdown links in docs
+      uses: gaurav-nelson/github-action-markdown-link-check@v1
+      with:
+        config-file: '.github/workflows/link-checker.config.json'
+        folder-path: 'docs/'
+
+    - name: Check markdown files in root
+      uses: gaurav-nelson/github-action-markdown-link-check@v1
+      with:
+        config-file: '.github/workflows/link-checker.config.json'
+        # ignore subfolders we don't want to check everthing, there is a lot of files from plugins that we don't control
+        max-depth: 0

CONTRIBUTING.md

@@ -15,7 +15,7 @@ yarn tsc                                                           # Run type ge
 
 ### Run the Showcase App
 
-We currently have quite a bit of moving parts for the showcase application. As such, we have documentation dedicated to the requirements for running the showcase app under [getting-started.md](https://github.com/janus-idp/backstage-showcase/blob/main/showcase-docs/getting-started.md).
+We currently have quite a bit of moving parts for the showcase application. As such, we have documentation dedicated to the requirements for running the showcase app under [getting-started.md](https://github.com/janus-idp/backstage-showcase/blob/main/docs/index.md).
 
 ### Useful Scripts
 

README.md

@@ -1,4 +1,4 @@
-# [Janus Showcase](https://showcase.janus-idp.io)
+# Janus Showcase
 
 [0]: https://quay.io/repository/janus-idp/backstage-showcase
 
@@ -16,7 +16,7 @@ Today, we have several plugins integrated into the showcase app as a way to demo
 
 Our current list of plugins within the showcase app include:
 
-- [OCM plugin](https://github.com/backstage/comunity-plugins/tree/main/workspaces/ocm/plugins/ocm)
+- [OCM plugin](https://github.com/backstage/community-plugins/tree/main/workspaces/ocm/plugins/ocm)
 - [Quay plugin](https://github.com/backstage/community-plugins/tree/main/workspaces/quay/plugins/quay)
 - [Kubernetes plugin](https://github.com/backstage/backstage/tree/master/plugins/kubernetes)
 - [Topology plugin](https://github.com/janus-idp/backstage-plugins/tree/main/plugins/topology)
@@ -53,30 +53,20 @@ Dependencies:
 - [Node.js](https://nodejs.org/en/) 18
 - [yarn](https://classic.yarnpkg.com/en/docs/install#debian-stable)
 
-Information on running the showcase app can be found in our [Getting Started](https://github.com/janus-idp/backstage-showcase/blob/main/showcase-docs/getting-started.md) documentation. In the documentation is how to set up and run an instance of the showcase app locally. We plan to expand upon the documentation at a later point if there is enough interest in other methods for getting the app up and running.
+Information on running the showcase app can be found in our [Getting Started](https://github.com/janus-idp/backstage-showcase/blob/main/docs/index.md) documentation. In the documentation is how to set up and run an instance of the showcase app locally. We plan to expand upon the documentation at a later point if there is enough interest in other methods for getting the app up and running.
 
 We are excited to see people wanting to contribute to our project and welcome anyone who wishes to participate. You are more than welcome to browse through our open issues and tackle anything you feel confident in working on.
 
 We also welcome non code contributions in the form of bug reporting and documentation writing. If you run across any bugs in the showcase app, please raise an issue here in [GitHub](https://github.com/janus-idp/backstage-showcase/issues/new?assignees=&labels=kind%2Fbug%2Cstatus%2Ftriage&template=bug.md).
 
 ## Community, Discussion, and Support
 
-The Janus Community meeting is held biweekly on Thursday at 1:30 UTC via [Google Meet](https://meet.google.com/taq-tpfs-rre). An [agenda](https://docs.google.com/document/d/1RYkKxBRj6uMT5PTIugAuxAIYK9WxTkKgqdcdw1752Dc/edit?usp=sharing) can be found for the meeting and we encourage you to add any topics that you wish to discuss.
-
-[Bugs](https://github.com/janus-idp/backstage-showcase/issues/new?assignees=&labels=kind%2Fbug%2Cstatus%2Ftriage&template=bug.md) should be filled out here on GitHub.
-
-Join the [community slack channel](https://join.slack.com/t/janus-idp/shared_invite/zt-1pxtehxom-fCFtF9rRe3vFqUiFFeAkmg) for a quick way to reach us or members of the community for discussion and collaboration.
-
-Want to see a plugin in the showcase? Create an [issue](https://github.com/janus-idp/backstage-showcase/issues/new?assignees=&labels=kind%2Ffeature%2Cstatus%2Ftriage&template=feature.md) and we will discuss if it is right for the project.
-
-Have an idea for a plugin? Submit a [proposal](https://github.com/janus-idp/backstage-plugins/issues/new?assignees=&labels=plugin&template=plugin.yaml&title=%F0%9F%94%8C+Plugin%3A+) to the Janus IDP Backstage Plugins repo.
+[Bugs](https://issues.redhat.com/projects/RHIDP) should be filled out here on RHIDP Jira.
 
 ## Resources
 
 Our [blog](https://janus-idp.io/blog) is a great way to see what we are up to.
 
-You can find the Backstage Showcase app running at <https://showcase.janus-idp.io>.
-
 For more information on our plugin offerings, consult the [Janus IDP Backstage Plugins](https://github.com/janus-idp/backstage-plugins) repo.
 
 Want to know more about Backstage, consult the [documentation](https://backstage.io/docs/overview/what-is-backstage) and [GitHub](https://github.com/backstage/backstage) repo.

docs/audit-log.md

@@ -53,7 +53,7 @@ The specified directory will be created automatically if it does not exist.
 
 ---
 
-By default, the audit log files will be in the following format: `redhat-developer-hub-audit-%DATE%.log` where `%DATE%` is the format specified in [`auditLog.rotateFile.dateFormat`](#configuring-the-file-rotation-frequency).
+By default, the audit log files will be in the following format: `redhat-developer-hub-audit-%DATE%.log` where `%DATE%` is the format specified in [`auditLog.rotateFile.dateFormat`](#configuring-file-retention-policy).
 
 To customize the log file name format, use:
 

docs/customization.md

@@ -42,7 +42,7 @@ dynamicPlugins:
 
 `default.<menu_item_name>`: The `default.` prefix is mandatory to ensure that the menu item is recognized as a main menu item. It should be used for both individual menu items and parent menu group configurations.
 
-See [Menu items](dynamic-plugins.md#menu-items) from dynamic-plugins documentation for more details.
+See [Menu items](dynamic-plugins/dynamic-plugins.md#menu-items) from dynamic-plugins documentation for more details.
 
 See [DefaultMainMenuItems](https://github.com/janus-idp/backstage-showcase/blob/main/packages/app/src/consts.ts#L1) for a list of main menu items, including their default priorities.
 

docs/dynamic-plugins/export-derived-package.md

@@ -130,4 +130,4 @@ export const DynamicEntityTechdocsContent = {
 };
 ```
 
-Important part of the frontend dynamic plugins is its layout configuration (bindings and routes). For more information on how to configure bindings and routes, see [Layout Configuration](layoud-configuration.md).
+Important part of the frontend dynamic plugins is its layout configuration (bindings and routes). For more information on how to configure bindings and routes, see [Frontend Plugin Wiring](frontend-plugin-wiring.md).

docs/dynamic-plugins/frontend-plugin-wiring.md

@@ -518,7 +518,7 @@ A plugin can specify multiple field extensions, in which case each field extensi
 
 ### Add a custom Backstage theme or replace the provided theme
 
-The look and feel of a Backstage application is handled by Backstage theming. Out of the box Developer Hub provides a theme with a number of [configuration overrides](./customization.md) that allow for user customization. It's also possible to provide additional Backstage themes as well as replace the out of box Developer Hub themes from a dynamic plugin.
+The look and feel of a Backstage application is handled by Backstage theming. Out of the box Developer Hub provides a theme with a number of [configuration overrides](../customization.md) that allow for user customization. It's also possible to provide additional Backstage themes as well as replace the out of box Developer Hub themes from a dynamic plugin.
 
 A dynamic plugin would export a theme provider function with a signature of `({ children }: { children: ReactNode }): React.JSX.Element`, for example:
 

docs/dynamic-plugins/installing-plugins.md

@@ -10,7 +10,7 @@ Plugins are defined in the `plugins` array in the `dynamic-plugin-config.yaml` f
 - `package`: The package definition of the plugin. This can be an OCI image, `tgz` archive, npm package, or a directory path.
 - `disabled`: A boolean value that determines whether the plugin is enabled or disabled.
 - `integrity`: The integrity hash of the package. This is required for `tgz` archives and npm packages.
-- `pluginConfig`: The configuration for the plugin. For backend plugins this is optional and can be used to pass configuration to the plugin. For frontend this is required, see [Layout Configuration](layoud-configuration.md) for more information on how to configure bindings and routes. This is fragment o the `app-config.yaml` file. Anything that is added to this object will be merged with the main app-config.yaml file.
+- `pluginConfig`: The configuration for the plugin. For backend plugins this is optional and can be used to pass configuration to the plugin. For frontend this is required, see [Frontend Plugin Wiring](frontend-plugin-wiring.md) for more information on how to configure bindings and routes. This is fragment o the `app-config.yaml` file. Anything that is added to this object will be merged with the main app-config.yaml file.
 
 ## Dynamic plugins included in the Showcase container image
 

docs/dynamic-plugins/packaging-dynamic-plugins.md

@@ -4,7 +4,7 @@
 To package a Backstage plugin as a dynamic plugin, you need access to its source code.
 
 First you need to create a derived package using the `@janus-idp/cli` and then package it into one of the supported formats.
-For detailed instructions on creating a derived package, see [Creating a Derived Dynamic Plugin Package](../creating-derived-package).
+For detailed instructions on creating a derived package, see [Export Derived Dynamic Plugin Package](export-derived-package.md).
 
 There are three possible packaging formats for dynamic plugins:
 
@@ -21,7 +21,7 @@ The derived dynamic plugin JavaScript packages should **not** be pushed to the p
 **Prerequisites:**
 
 - `podman` or `docker` installed on your system.
-- An exported derived dynamic plugin package (see: [Creating a Derived Dynamic Plugin Package](creating-derived-package.md).
+- An exported derived dynamic plugin package (see: [Export Derived Dynamic Plugin Package](export-derived-package.md).
 
 To package the plugin into an OCI image, use the `package package-dynamic-plugins` command from `@janus-idp/cli` in the plugin’s source code root directory (not in the `dist-dynamic` directory).
 
@@ -37,7 +37,7 @@ The `--tag` argument is required when using this packaging method. It specifies
 
 **Prerequisites:**
 
-- An exported derived dynamic plugin package (see: [Creating a Derived Dynamic Plugin Package](creating-derived-package.md).
+- An exported derived dynamic plugin package (see: [Export Derived Dynamic Plugin Package](export-derived-package.md).
 
 To package the plugin into a `tgz` archive, run the `npm pack` command in the `dist-dynamic` directory. This will create a `tgz` archive in the current directory that can be used to install the plugin.
 
@@ -84,7 +84,7 @@ oc new-app --image-stream=plugin-registry
 
 **Prerequisites:**
 
-- An exported derived dynamic plugin package (see: [Creating a Derived Dynamic Plugin Package](creating-derived-package.md).
+- An exported derived dynamic plugin package (see: [Export Derived Dynamic Plugin Package](export-derived-package.md).
 
 > [!WARNING]
 > Using your own internal npm registry to distribute derived dynamic plugin package is recommended.

docs/dynamic-plugins/wrapping-plugins.md

@@ -1,7 +1,7 @@
 # Wrapping a third-party backend plugin to add dynamic plugin support
 
 Unless you need to include plugin in the default RHDH container image, or you need to make some changes in the plugin source code, you don't need to wrap the plugin.
-You can just [export](creating-derived-package.md) plugin as a dynamic plugin and install it as described in the [Installing External Dynamic Plugins](installing-plugins.md#installing-external-dynamic-plugins) guide.
+You can just [export](export-derived-package.md) plugin as a dynamic plugin and install it as described in the [Installing External Dynamic Plugins](installing-plugins.md#installing-external-dynamic-plugins) guide.
 
 In order to add dynamic plugin support to a third-party backend plugin, without touching the third-party plugin source code, a wrapper plugin can be created that will:
 

docs/e2e-tests/README.md

@@ -36,7 +36,7 @@ yarn playwright install
 
 To incorporate a new test case, create a file with a `.spec.ts` extension in the `e2e-tests/playwright/e2e` directory.
 The tests within a spec file can run in parallel (by default) or sequentially if using the .serial like in [this example](../../e2e-tests/playwright/e2e/github-happy-path.spec.ts). Note that sequential execution is considered a bad practice and is strongly discouraged.
-Note that, in order to add or edit a test, you should adhere to the [contribution guidelines](CONTRIBUTING.md).
+Note that, in order to add or edit a test, you should adhere to the [contribution guidelines](./CONTRIBUTING.MD).
 
 ### Running the Tests
 
@@ -88,4 +88,3 @@ yarn showcase-1-2-x                 # Runs the showcase 1.2.x test suite
 yarn showcase-rbac-1-2-x            # Runs the showcase RBAC 1.2.x test suite
 ```
 
-For more information on how the tests run in the CI, see [this document](CI.md)

docs/index.md

@@ -238,14 +238,14 @@ The easiest and fastest method for getting started: Backstage Showcase app, runn
    - Setup the PagerDuty plugin
 
      - `${PAGERDUTY_TOKEN}` with the [API token](https://support.pagerduty.com/docs/api-access-keys#generating-a-general-access-rest-api-key) used to make requests to the [PagerDuty API](https://developer.pagerduty.com/docs/rest-api-v2/rest-api/). Note that this will require a PaperDuty Admin role.
-     - To integrate with a PagerDuty Service, you will need to annotate the appropriate entity with the [PagerDuty Integration key](https://github.com/backstage/backstage/tree/master/plugins/pagerduty#integrating-with-a-pagerduty-service) in its `.yaml` configuration file:
+     - To integrate with a PagerDuty Service, you will need to annotate the appropriate entity with the [PagerDuty Integration key](https://pagerduty.github.io/backstage-plugin-docs/getting-started/pagerduty/) in its `.yaml` configuration file:
 
      ```yaml
      annotations:
        pagerduty.com/integration-key: [INTEGRATION_KEY]
      ```
 
-     - Alternatively, you can integrate with the [PagerDuty ServiceID](https://github.com/backstage/backstage/tree/master/plugins/pagerduty#annotating-with-service-id) instead of the integration key:
+     - Alternatively, you can integrate with the [PagerDuty ServiceID](https://pagerduty.github.io/backstage-plugin-docs/getting-started/backstage/#annotating-entities) instead of the integration key:
 
      ```yaml
      annotations:
@@ -272,7 +272,7 @@ The easiest and fastest method for getting started: Backstage Showcase app, runn
 
    - Setup the Dynatrace plugin
 
-     - This [URL](https://github.com/backstage/backstage/tree/master/plugins/dynatrace#getting-started) explains how to use the Dynatrace Plugin
+     - This [URL](https://github.com/backstage/community-plugins/tree/main/workspaces/dynatrace/plugins/dynatrace#getting-started) explains how to use the Dynatrace Plugin
      - `${DYNATRACE_URL}`: The baseURL for rendering links to problems in the table
      - `${DYNATRACE_API_URL}`: The URL to the Dynatrace API
      - `{DYNATRACE_ACCESS_TOKEN}`: API access token (see [documentation](https://www.dynatrace.com/support/help/dynatrace-api/basics/dynatrace-api-authentication)) with `entities.read`,`problems.read` permissions. It will also need one of the following permissions: `DataExport`, `ExternalSyntheticIntegration`, or `ReadSyntheticData`.

docs/mkdocs.yml

@@ -0,0 +1,4 @@
+site_name: Documentation Site
+docs_dir: docs
+plugins:
+  - techdocs-core

docs/monitoring-and-logging.md

@@ -16,7 +16,7 @@ When deploying Backstage Showcase onto a kubernetes cluster with the [RHDH Helm
 
 ### Enabling Metrics Monitoring on Openshift
 
-To enable metrics monitoring on OpenShift, we need to create a `ServiceMonitor` resource in the OpenShift cluster that will be used by Prometheus to scrape metrics from your Backstage instance. For the metrics to be ingested by the built-in Prometheus instances in Openshift, please ensure you enabled [monitoring for user-defined projects](https://docs.openshift.com/container-platform/4.16/observability/monitoring/enabling-monitoring-for-user-defined-projects.html#enabling-monitoring-for-user-defined-projects).
+To enable metrics monitoring on OpenShift, we need to create a `ServiceMonitor` resource in the OpenShift cluster that will be used by Prometheus to scrape metrics from your Backstage instance. For the metrics to be ingested by the built-in Prometheus instances in Openshift, please ensure you enabled [monitoring for user-defined projects](https://docs.openshift.com/container-platform/latest/observability/monitoring/enabling-monitoring-for-user-defined-projects.html).
 
 #### Helm deployment
 
@@ -174,13 +174,13 @@ For the _metrics_ add-on, we can modify the [`ama-metrics-settings-configmap`](h
 
 Alternatively, we will can instead add/modify the `ama-metrics-prometheus-config` Config Map in the `kube-system` namespace of the AKS cluster to configure custom scrape jobs. In the [example Config Map](./configuration_files/ama-metrics-prometheus-config.yaml), please replace the values of namespace with the namespace you the backstage instance into. For more information on how to configure this refer to the [official Azure docs](https://learn.microsoft.com/en-us/azure/azure-monitor/containers/prometheus-metrics-scrape-configuration#configure-custom-prometheus-scrape-jobs).
 
-To view the metrics, you can create a Grafana instance, [connect it to the Azure Monitor workspace](https://docs.microsoft.com/en-us/azure/azure-monitor/visualize/tutorial-logs-dashboards-with-grafana#connect-grafana-to-azure-monitor) and view the metrics using PromQL queries.
+To view the metrics, you can create a Grafana instance, [configure an Azure Monitor data source plug-in](https://learn.microsoft.com/en-us/azure/azure-monitor/visualize/grafana-plugin#configure-an-azure-monitor-data-source-plug-in) and view the metrics using PromQL queries.
 
 #### Monitoring Add-on
 
 For the _monitoring_ add-on, we will need to add the a modified instance of this [Config Map](https://raw.githubusercontent.com/microsoft/Docker-Provider/ci_prod/kubernetes/container-azm-ms-agentconfig.yaml) to the `kube-system` namespace of the AKS cluster. In the [example Config Map](./configuration_files/container-azm-ms-agentconfig.yaml), please replace the values of namespace with the namespace you deployed the backstage instance into. For more information refer to the [official Azure docs](https://learn.microsoft.com/en-us/azure/azure-monitor/containers/container-insights-prometheus-logs?tabs=cluster-wide).
 
-To view the metrics, you can create a Grafana instance, [connect it to the Azure Monitor workspace](https://docs.microsoft.com/en-us/azure/azure-monitor/visualize/tutorial-logs-dashboards-with-grafana#connect-grafana-to-azure-monitor) and view the metrics using PromQL queries.
+To view the metrics, you can create a Grafana instance, [configure an Azure Monitor data source plug-in](https://learn.microsoft.com/en-us/azure/azure-monitor/visualize/grafana-plugin#configure-an-azure-monitor-data-source-plug-in) and view the metrics using PromQL queries.
 
 Alternatively, you can use [Log Analytics](https://learn.microsoft.com/en-us/azure/azure-monitor/containers/container-insights-log-query#prometheus-metrics) to query the metrics using KQL. The following is an example query to get a custom metric for the Backstage instance: