Add workflow for linting and markdown-link-check (#87)

- Add workflow for linting. - Add script to check markdown links. - Add explanation to script. - Add github workflow for link-check. - Add README for github workflows. --------- Signed-off-by: Mirjam Aulbach <[email protected]>
Aiven-Open · Sep 25, 2023 · 739c286 · 739c286
1 parent e82a34c
commit 739c286
Show file tree

Hide file tree

Showing 48 changed files with 749 additions and 183 deletions.
diff --git a/.github/README.md b/.github/README.md
@@ -0,0 +1,18 @@
+# Overview GitHub workflows
+
+This document explains how and why we organize our workflows for a CI strategy using GitHub actions.
+
+## Directories and file structure
+
+Our directory structure is as follows:
+
+- 📁 `/workflows` contains GitHub workflow files
+
+## Pipeline
+
+When a Pull Request is opened targeting `main`, these workflows are triggered:
+
+- [`pull-request`](./workflows/pull-request.yaml)
+  - runs linting and code / markdown formatting checks
+- [`link-check`](./workflows/link-check.yaml)
+  - checks that internal links are correct
diff --git a/.github/workflows/link-check.yaml b/.github/workflows/link-check.yaml
@@ -0,0 +1,39 @@
+name: "Link check for internal links"
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "**.md"
+  pull_request:
+    branches: ["main"]
+    paths:
+      - "**.md"
+
+jobs:
+  link-checker:
+    name: Check internal and external links in markdown files
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3df4ab11eba7bda6032a0b82a6bb43b11571feac #v4.0.0
+        with:
+          ref: ${{ github.ref }}
+          fetch-depth: 0
+
+      - name: Set Node version
+        id: versions
+        shell: bash
+        run: |
+          NODE_VERSION=$(jq -r '.engines.node' package.json)
+          echo "NODE_VERSION=$NODE_VERSION" >> $GITHUB_OUTPUT
+
+      - name: Setup node.js
+        uses: actions/setup-node@64ed1c7eab4cce3362f8c340dee64e5eaeef8f7c # v3.6.0
+        with:
+          node-version: ${{ steps.versions.outputs.NODE_VERSION }}
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Run markdown link check
+        run: npm run markdown-link-check -- -q -o
diff --git a/.github/workflows/pull-request.yaml b/.github/workflows/pull-request.yaml
@@ -0,0 +1,39 @@
+name: "Static code and markdown analysis"
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  static_analysis:
+    name: Static analysis code and markdown
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3df4ab11eba7bda6032a0b82a6bb43b11571feac #v4.0.0
+        with:
+          ref: ${{ github.ref }}
+          fetch-depth: 0
+
+      - name: Set Node version
+        id: versions
+        shell: bash
+        run: |
+          NODE_VERSION=$(jq -r '.engines.node' package.json)
+          echo "NODE_VERSION=$NODE_VERSION" >> $GITHUB_OUTPUT
+
+      - name: Setup node.js
+        uses: actions/setup-node@64ed1c7eab4cce3362f8c340dee64e5eaeef8f7c # v3.6.0
+        with:
+          node-version: ${{ steps.versions.outputs.NODE_VERSION }}
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Linting code files
+        run: npm run lint:code
+
+      - name: Linting markdown files
+        run: npm run lint:markdown
diff --git a/.markdownlint.json b/.markdownlint.json
@@ -2,5 +2,6 @@
   "default": true,
   "MD013": false,
   "MD030": false,
-  "MD046": false
+  "MD046": false,
+  "MD051": false
 }
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # Klaw documentation
 
-- Please be aware of our [Code of Conduct](/CODE_OF_CONDUCT.md) ❤️
+- Please be aware of our [Code of Conduct](CODE_OF_CONDUCT.md) ❤️
 
 ## About
 
@@ -35,15 +35,22 @@ npm start
 ℹ️ You can see all our scripts in the [`package.json`](package.json).
 You can also run `npm run` in your console to get a list of all available scripts.
 
+Please note that you have to set up your [local development](#installation-and-usage) in order to use the scripts.
+
 Here are the important ones you're likely to use:
 
 - `npm start`: starts the app for development
 - `npm run build`: will build the documentation site and generate all static files in "build". After `build` you can
   run `npm run serve` to test your build locally
-- `lint`: runs a format check and if no error is found, lints code and markdown files in the project.
+- `npm run lint`: runs a format check and if no error is found, lints code and markdown files in the project.
   - the linting script does not mutate your code. See [Linting and code formatting](#linting-and-code-formatting) for
     more info.
-- `reformat`: runs the code formatter (prettier) as well as the markdown linter in fix mode. This will mutate you code.
+- `npm run reformat`: runs the code formatter (prettier) as well as the markdown linter in fix mode. This will mutate
+- `npm run markdown-link-check`: checks if there are any broken links. Note: This requires internet connection, as it
+  does check external links, too!
+  - Run `npm run markdown-link-check -- -o` to only check for internal links (offline mode).
+  - Run `npm run markdown-link-check -- -q` to only log failures.
+  - Run `npm run markdown-link-check -- -f /path/your-file.md` to run checks for only one file.
 
 ℹ️ We are using a custom hook path for enabling pre-commit hooks. This path is set in the local git config when
 running `npm install`.

diff --git a/blog/2023/09/schema-management-disaster-recovery-in-klaw.md b/blog/2023/09/schema-management-disaster-recovery-in-klaw.md
@@ -176,7 +176,7 @@ Select the schemas you want to sync with the cluster. Once you submit your choic
 schemas directly into your designated schema registry environment.
 
 For more information on this synchronization process, refer to
-**[sync-schemas-to-cluster](../../../docs/HowTo/kafka-cluster-migration/sync-schemas-to-cluster)**
+**[sync-schemas-to-cluster](/docs/HowTo/kafka-cluster-migration/sync-schemas-to-cluster)**
 
 The following video demonstrates migrating schemas to a Schema Registry, specifically focusing on a couple of subjects
 already stored in Klaw.

diff --git a/docs/Concepts/index.md b/docs/Concepts/index.md
@@ -1,11 +1,11 @@
 # Concepts
 
-- [Workflows](workflows)
-- [Users & Teams](users-teams)
-- [Clusters & Environments](clusters-environments)
-- [Synchronize](synchronize)
-- [Metastore data](metastore)
-- [Advanced configuration](config)
-- [Promotion](promotion)
-- [Switch Teams](switch-teams)
-- [High Availability](high-availability)
+- [Workflows](workflows.md)
+- [Users & Teams](users-teams.md)
+- [Clusters & Environments](clusters-environments.md)
+- [Synchronize](synchronize.md)
+- [Metastore data](metastore.md)
+- [Advanced configuration](config.md)
+- [Promotion](promotion.md)
+- [Switch Teams](switch-teams.md)
+- [High Availability](high-availability.md)
diff --git a/docs/Concepts/switch-teams.md b/docs/Concepts/switch-teams.md
@@ -12,7 +12,7 @@ To switch between teams in Klaw,
 - Users must have the switch teams option enabled in their profile. A
   user's profile must also include the user's base team and a list
   of available teams for switching. To learn how to enable switch
-  teams, see [details](../HowTo/teams/switch-teams)
+  teams, see [details](../HowTo/teams/switch-teams.md)
 - Only superadmin or a user with `ADD_EDIT_DELETE_USERS` permission
   can enable a user profile to switch teams,
 - Once the option to switch teams is enabled, users can easily switch

diff --git a/docs/HowTo/authentication/index.md b/docs/HowTo/authentication/index.md
@@ -2,8 +2,8 @@
 
 How to authenticate a user in Klaw.
 
-- [UserPwd](userpwd-db)
-- [Windows AD](windows-ad)
-- [Azure AD](azure-ad)
-- [Google Account](google-account)
-- [Third Party account](third-party-account)
+- [UserPwd](userpwd-db.md)
+- [Windows AD](windows-ad.md)
+- [Azure AD](azure-ad.md)
+- [Google Account](google-account.md)
+- [Third Party account](third-party-account.md)
diff --git a/docs/HowTo/clusterconnectivity/confluent-cloud-kafka-cluster-ssl-protocol.md b/docs/HowTo/clusterconnectivity/confluent-cloud-kafka-cluster-ssl-protocol.md
@@ -12,10 +12,14 @@ cluster with Klaw. The following functionalities are available in Klaw for Confl
 - Sync Topics
 - Sync ACLs
 
-References :
+References:
 
-<https://docs.confluent.io/cloud/current/api.html#tag/Topic-(v3)>
-<https://docs.confluent.io/cloud/current/api.html#tag/ACL-(v3)>
+[//]: # "<!-- markdown-link-check-disable -->"
+
+- <https://docs.confluent.io/cloud/current/api.html#tag/Topic-(v3)>
+- <https://docs.confluent.io/cloud/current/api.html#tag/ACL-(v3)>
+
+[//]: # "<!-- markdown-link-check-enable -->"
 
 ## Prerequisite
 

diff --git a/docs/HowTo/clusterconnectivity/index.md b/docs/HowTo/clusterconnectivity/index.md
@@ -2,25 +2,25 @@
 
 Efficiently manage connections between Klaw and various Kafka cluster types.
 
-- [Klaw database connection](klaw-db-connection)
+- [Klaw database connection](klaw-db-connection.md)
 
-- [Connect Klaw Core and Klaw Cluster APIs](klaw-core-with-clusterapi)
+- [Connect Klaw Core and Klaw Cluster APIs](klaw-core-with-clusterapi.md)
 
-- [Connect to Apache Kafka cluster using SSL protocol](kafka-cluster-ssl-protocol)
+- [Connect to Apache Kafka cluster using SSL protocol](kafka-cluster-ssl-protocol.md)
 
-- [Connect to Apache Kafka cluster using SASL protocol](kafka-cluster-sasl-ssl-protocol)
+- [Connect to Apache Kafka cluster using SASL protocol](kafka-cluster-sasl-ssl-protocol.md)
 
-- [Connect to Schema Registry cluster](sr-cluster-ssl-protocol)
+- [Connect to Schema Registry cluster](sr-cluster-ssl-protocol.md)
 
-- [Connect with Aiven for Apache Kafka® cluster using SSL protocol](aiven-kafka-cluster-ssl-protocol)
+- [Connect with Aiven for Apache Kafka® cluster using SSL protocol](aiven-kafka-cluster-ssl-protocol.md)
 
-- [Connect with Aiven For Apache Kafka® cluster using SASL protocol](aiven-kafka-cluster-sasl-ssl-protocol)
+- [Connect with Aiven For Apache Kafka® cluster using SASL protocol](aiven-kafka-cluster-sasl-ssl-protocol.md)
 
-- [Connect to Karapace schema registry](aiven-karapace-cluster-ssl-protocol)
+- [Connect to Karapace schema registry](aiven-karapace-cluster-ssl-protocol.md)
 
-- [Aiven For Apache Kafka Connect cluster](aiven-kafka-connect-cluster-ssl-protocol)
+- [Aiven For Apache Kafka Connect cluster](aiven-kafka-connect-cluster-ssl-protocol.md)
 
-- [Connect with Confluent Cloud Kafka® cluster using SSL protocol](confluent-cloud-kafka-cluster-ssl-protocol)
+- [Connect with Confluent Cloud Kafka® cluster using SSL protocol](confluent-cloud-kafka-cluster-ssl-protocol.md)
 
 Klaw supports the following Kafka flavors:
 

diff --git a/docs/HowTo/clusters.md b/docs/HowTo/clusters.md
@@ -26,14 +26,16 @@ To add a new cluster in Klaw, follow these steps:
 3. On the **Clusters** screen, select **Add Cluster**.
 4. On the **Add Kafka Cluster** screen, provide the following information:
 
-   - **Cluster type**: Choose a cluster type from the dropdown menu (Kafka, Schema Registry, or Kafka Connect). Based on the cluster type, you need to include additional information.
+   - **Cluster type**: Choose a cluster type from the dropdown menu (Kafka, Schema Registry, or Kafka Connect). Based
+     on the cluster type, you need to include additional information.
    - **Cluster name**: Enter a name for the cluster, for example, Dev_cluster.
    - **Kafka flavor**: Select a Kafka flavor from the dropdown list.
      - Provide the additional information required based on the **cluster type**:
        - If you are adding a **Kafka cluster**, enter the following:
          - **Protocol**: Select either plaintext or SSL.
-         - **RestAPI servers**: Enter the URL of the REST API servers, for example, <https://server:12695>.
-         - **Bootstrap servers**: Enter the comma-separated list of bootstrap servers, for example, `server1:9092,server2:9092,server3:9092`.
+         - **RestAPI servers**: Enter the URL of the REST API servers, for example, `https://server:12695`.
+         - **Bootstrap servers**: Enter the comma-separated list of bootstrap servers, for
+           example, `server1:9092,server2:9092,server3:9092`.
        - If you are adding a **Schema Registry cluster**, enter the following:
          - **Protocol**: Select either plaintext or SSL.
          - **Bootstrap servers**: Enter the comma-separated list of bootstrap servers.
@@ -69,7 +71,8 @@ To delete a cluster, follow these steps:
 3. Click the **Delete** icon in the **Actions** column for the cluster
    you want to delete.
 
-   You can only delete clusters that are not associated with any environment. If a cluster is associated with any environment, you must remove the environment association before deleting the cluster.
+   You can only delete clusters that are not associated with any environment. If a cluster is associated with any
+   environment, you must remove the environment association before deleting the cluster.
 
 4. On the confirmation screen, select **delete** to confirm the deletion of
    the cluster. The selected cluster is deleted.

diff --git a/docs/HowTo/connectors/Request-a-new-connector.md b/docs/HowTo/connectors/Request-a-new-connector.md
@@ -8,7 +8,7 @@ Kafka Connector.
 ## Prerequisites
 
 - The Superadmin must configure the environment within Klaw. See
-  [Environments](../../Concepts/clusters-environments) for the steps to configure the environments.
+  [Environments](../../Concepts/clusters-environments.md) for the steps to configure the environments.
 
 ## Make a connector request
 

diff --git a/docs/HowTo/connectors/index.md b/docs/HowTo/connectors/index.md
@@ -28,10 +28,10 @@ them to other environments, including production. The team that owns the
 connector is responsible for making the final decision related to any
 requests, such as approving or declining them.
 
-- [Request a new Connector](Request-a-new-connector)
+- [Request a new Connector](Request-a-new-connector.md)
 
-- [Approve a Connector](Approve-a-connector)
+- [Approve a Connector](Approve-a-connector.md)
 
-- [My Connector Requests](My-connector-requests)
+- [My Connector Requests](My-connector-requests.md)
 
-- [Manage Connectors](manage-connectors)
+- [Manage Connectors](manage-connectors.md)
diff --git a/docs/HowTo/exportimport/index.md b/docs/HowTo/exportimport/index.md
@@ -5,6 +5,6 @@ instance are important operations. These features provided by Klaw serve
 the purpose of disaster recovery and migrations, ensuring data security
 and smooth transitions.
 
-- [Export Klaw data](exportdata)
+- [Export Klaw data](exportdata.md)
 
-- [Import Klaw data](importdata)
+- [Import Klaw data](importdata.md)
diff --git a/docs/HowTo/index.md b/docs/HowTo/index.md
@@ -2,23 +2,23 @@
 
 How to install and configure Klaw.
 
-- [Installation](installation)
-- [Manage Klaw connections](clusterconnectivity)
-- [Authentication](authentication)
-- [Authorization](authorization)
-- [Kafka Cluster Migration](kafka-cluster-migration)
-- [Topics](topics)
-- [Subscriptions](subscriptions)
-- [Schemas](schemas)
-- [Connectors](connectors)
-- [Teams](teams)
-- [Users](users)
-- [Roles Permissions](rolespermissions)
-- [Notifications](notifications)
-- [Clusters](clusters)
-- [Environments](environments)
-- [Tenants](tenant)
-- [Analytics](analytics)
-- [Settings](settings)
-- [Export Import Klaw data](exportimport)
-- [Others](zothers)
+- [Installation](installation/index.md)
+- [Manage Klaw connections](clusterconnectivity/index.md)
+- [Authentication](authentication/index.md)
+- [Authorization](authorization.md)
+- [Kafka Cluster Migration](kafka-cluster-migration/index.md)
+- [Topics](topics/index.md)
+- [Subscriptions](subscriptions/index.md)
+- [Schemas](schemas/index.md)
+- [Connectors](connectors/index.md)
+- [Teams](teams/index.md)
+- [Users](users.md)
+- [Roles Permissions](rolespermissions.md)
+- [Notifications](notifications/index.md)
+- [Clusters](clusters.md)
+- [Environments](environments.md)
+- [Tenants](tenant.md)
+- [Analytics](analytics.md)
+- [Settings](settings.md)
+- [Export Import Klaw data](exportimport/index.md)
+- [Others](zothers.md)
diff --git a/docs/HowTo/installation/index.md b/docs/HowTo/installation/index.md
@@ -2,7 +2,9 @@
 
 Klaw can be installed and configured in two ways:
 
-- [Run From Source](run-source)
-- [Run from Docker](run-docker)
+- [Run From Source](run-source.md)
+- [Run from Docker](run-docker.md)
 
-Once Klaw is installed, you can use the [Configure Klaw Wizard](configure-klaw-wizard) to configure your Kafka cluster and start managing your Kafka resources.
+Once Klaw is installed, you can use the [Configure Klaw Wizard](configure-klaw-wizard.md) to configure your Kafka
+cluster
+and start managing your Kafka resources.