upgrade: docusaurus 3!!! (#4799)

* d3: bump dependencies to minimum docusaurus 3.0

* d3: remove as many broken things as possible (#4800)

* temp: remove docLayoutComponent setting

* temp: remove old versions

* temp: remove broken theme components

* d3: remove configuration for older versions

* d3: regenerate vNext API docs (#4801)

* d3: regenerate camunda api docs, vNext

* d3: regenerate operate api docs, vNext

* d3: regenerate tasklist api docs, vNext

* d3: regenerate admin sm api docs, vNext

* fix: update badge removal regex and regen vNext API docs to scrub the duplicate badges

* d3: regen 8.6 API docs (#4805)

* feat: rewrite api generation to support older versions; configure v8.6 of operate API generation

* oops: remove notes

* fix: regenerate 8.6 operate api docs to accommodate updated plugin

* feat: configure 8.6 tasklist api generation

* fix: regenerate 8.6 tasklist api docs to accommodate updated plugin

* feat: configure 8.6 admin-sm api generation

* fix: regenerate 8.6 admin-sm api docs to accommodate updated plugin

* feat: configure 8.6 camunda api generation

* fix: regenerate 8.6 camunda api docs to accommodate updated plugin

* fix: revert id of sm-admin 8.6 info page

* feat: configure 8.6 zeebe api generation

* fix: regenerate 8.6 zeebe api docs to accommodate updated plugin

* d3: fix alpha URLs for 8.6 c8 REST API docs (#4828)

* fix: accommodate different alpha URLs per version in C8 REST docs

* fix: regen c8 REST docs for v8.6, with correct alpha URL.

* fix: adapt to change in react-prisma-renderer API

* d3: reintroduce 8.5 docs (#4872)

* d3: reintroduce 8.5 docs

* d3: configure 8.5 operate api docs

* d3: regenerate 8.5 operate api docs

* d3: configure 8.5 tasklist api docs

* d3: regen 8.5 tasklist api docs

* d3: configure 8.5 zeebe api docs

* d3: regen 8.5 zeebe api docs

* fix: remove unused image reference for file that doesn't exist

* fix: adapt to change in react-prisma-renderer API

* regenerate camunda/next api

* regen camunda api

* d3: reintroduce 8.4 docs (#4928)

* reintroduce 8.4 versions

* configure 8.4 operate api docs

* regenerate 8.4 operate api docs

* configure 8.4 tasklist api docs

* regenerate 8.4 tasklist api docs

* fix some broken links

* d3: reintroduce 8.3 docs (#4929)

* reenable 8.3 version

* fix dependency URL

* fix broken links

* remove obsolete config item

* bump to latest docusaurus (#4932)

* the curl icon is dead, long live the curl icon.

* d3: rewrite Metadata override (#4937)

* rewrite Metadata override

* add some guidance for pre-commit hook

* fix tests

* adjust archival theme component based on moved API

* re-introduce DocCard override

.husky/pre-commit

@@ -1,4 +1,6 @@
 #!/bin/sh
+# Before adding version-manager code here, read https://typicode.github.io/husky/how-to.html#solution.
+
 . "$(dirname "$0")/_/husky.sh"
 
 npx lint-staged

api/administration-sm/generation-strategy.js

@@ -1,21 +1,17 @@
 const { makeServerDynamic } = require("../make-server-dynamic");
 const removeDuplicateVersionBadge = require("../remove-duplicate-version-badge");
 
-const outputDir = "docs/apis-tools/administration-sm-api/specifications";
-const specFile = "api/administration-sm/administration-sm-openapi.yaml";
-
-function preGenerateDocs() {
-  makeServerDynamic(specFile);
+function preGenerateDocs(config) {
+  makeServerDynamic(config.specPath);
 }
 
-function postGenerateDocs() {
+function postGenerateDocs(config) {
   removeDuplicateVersionBadge(
-    `${outputDir}/administration-api-self-managed.info.mdx`
+    `${config.outputDir}/administration-api-self-managed.info.mdx`
   );
 }
 
 module.exports = {
-  outputDir,
   preGenerateDocs,
   postGenerateDocs,
 };

api/administration-sm/version-8.6/administration-sm-openapi.yaml

@@ -0,0 +1,249 @@
+openapi: 3.0.0
+components:
+  examples: {}
+  headers: {}
+  parameters: {}
+  requestBodies: {}
+  responses: {}
+  schemas:
+    ConsoleSMAdminApi.UsageMetricsInstances:
+      properties:
+        total:
+          type: number
+          format: double
+          description: The number of usage metrics for a specific type.
+      required:
+        - total
+      type: object
+      additionalProperties: false
+    ConsoleSMAdminApi.UsageMetricsTaskUsers:
+      properties:
+        total:
+          type: number
+          format: double
+          description: The number of usage metrics for a specific type.
+        assignees:
+          items:
+            type: string
+          type: array
+          description: The users that tasks have been assigned to.
+      required:
+        - total
+        - assignees
+      type: object
+      additionalProperties: false
+    ConsoleSMAdminApi.UsageMetricsForCluster:
+      properties:
+        id:
+          type: string
+          description: The identifier of the cluster.
+        processInstances:
+          $ref: "#/components/schemas/ConsoleSMAdminApi.UsageMetricsInstances"
+          description: The usage metrics for started process instances.
+        decisionInstances:
+          $ref: "#/components/schemas/ConsoleSMAdminApi.UsageMetricsInstances"
+          description: The usage metrics for executed decision instances.
+        taskUsers:
+          $ref: "#/components/schemas/ConsoleSMAdminApi.UsageMetricsTaskUsers"
+          description: The usage metrics for assigned task users.
+      required:
+        - id
+        - processInstances
+        - decisionInstances
+        - taskUsers
+      type: object
+      additionalProperties: false
+    ConsoleSMAdminApi.Status:
+      type: string
+      enum:
+        - healthy
+        - unhealthy
+        - unknown
+    ConsoleSMAdminApi.ClusterType:
+      type: string
+      enum:
+        - automation
+        - management
+    ConsoleSMAdminApi.AppType:
+      type: string
+      enum:
+        - zeebe-broker
+        - zeebe-gateway
+        - operate
+        - tasklist
+        - optimize
+        - modeler
+        - console
+        - identity
+        - unknown
+    ConsoleSMAdminApi.App:
+      properties:
+        type:
+          $ref: "#/components/schemas/ConsoleSMAdminApi.AppType"
+          description:
+            What application is running in the cluster, like Zeebe, Operate,
+            Tasklist, ...
+        id:
+          type: string
+          description: Unique identifier of the application
+        status:
+          $ref: "#/components/schemas/ConsoleSMAdminApi.Status"
+          description: Indicates if an application is healthy or not
+        url:
+          type: string
+          description: The public URL of the application
+        generation:
+          type: string
+          description: This is the current version of the running application
+        readiness:
+          type: string
+          description: The readiness URL of the application
+        metrics:
+          type: string
+          description: The metrics URL of the application
+      required:
+        - type
+        - id
+        - status
+        - url
+        - generation
+      type: object
+      additionalProperties: false
+    ConsoleSMAdminApi.Cluster:
+      properties:
+        uuid:
+          type: string
+          description: Unique identifier of the cluster
+        name:
+          type: string
+          description: Name of the cluster
+        namespace:
+          type: string
+          description: Namespace the cluster is running in.
+        status:
+          $ref: "#/components/schemas/ConsoleSMAdminApi.Status"
+          description: Indicates if a cluster is healthy or not
+        generation:
+          type: string
+          description: This is the current version of the running cluster
+        type:
+          $ref: "#/components/schemas/ConsoleSMAdminApi.ClusterType"
+          description:
+            We're distinguishing between automation and management clusters.
+            Management clusters include applications that act globally in an
+            installed context, like Console or Modeler. Automation clusters are
+            the Zeebe clusters including applications like Operate, Tasklist and
+            Optimize.
+        apps:
+          items:
+            $ref: "#/components/schemas/ConsoleSMAdminApi.App"
+          type: array
+          description: The list of applications running in the cluster
+      required:
+        - uuid
+        - name
+        - namespace
+        - status
+        - generation
+        - type
+        - apps
+      type: object
+      additionalProperties: false
+  securitySchemes:
+    bearer:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+info:
+  title: Administration API (Self-Managed)
+  description: Access the administration API of Console Self-Managed.
+  version: 1.0.0
+  contact:
+    url: https://www.camunda.com
+  license:
+    name: License
+    url: https://docs.camunda.io/docs/reference/licenses/
+paths:
+  /admin-api/usage-metrics:
+    get:
+      operationId: getUsageMetrics
+      responses:
+        "200":
+          description: Ok
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ConsoleSMAdminApi.UsageMetricsForCluster"
+        "403":
+          description: Forbidden
+        "500":
+          description: Server-side error
+      description: Returns usage metrics for a specific cluster for a given time
+        range. The usage metrics are aggregated over the time range and include
+        number of started process instances, executed decision instances, and
+        assigned task users.
+      summary: Get usage metrics for clusters
+      tags:
+        - Usage Metrics
+      security:
+        - bearer: []
+      parameters:
+        - description: The unique identifier of the cluster
+          in: query
+          name: id
+          required: true
+          schema:
+            type: string
+        - description:
+            The start timestamp of the time range as UNIX timestamp in
+            milliseconds
+          in: query
+          name: start
+          required: true
+          schema:
+            format: double
+            type: number
+        - description: The end timestamp of the time range as UNIX timestamp in milliseconds
+          in: query
+          name: end
+          required: true
+          schema:
+            format: double
+            type: number
+  /admin-api/clusters:
+    get:
+      operationId: getClusters
+      responses:
+        "200":
+          description: Ok
+          content:
+            application/json:
+              schema:
+                items:
+                  $ref: "#/components/schemas/ConsoleSMAdminApi.Cluster"
+                type: array
+        "403":
+          description: Forbidden
+        "500":
+          description: Server-side error
+      description:
+        Returns a list of all automation and management clusters. Each
+        cluster entry contains the running apps and their status.
+      summary: Get current clusters
+      tags:
+        - Clusters
+      security:
+        - bearer: []
+      parameters: []
+servers:
+  - url: "{schema}://{host}:{port}"
+    variables:
+      host:
+        default: localhost
+        description: The hostname of the API server.
+      port:
+        default: "8080"
+        description: The port of the API server.
+      schema:
+        default: http
+        description: The schema of the API server.

api/camunda/generation-strategy.js

@@ -1,11 +1,9 @@
 const removeDuplicateVersionBadge = require("../remove-duplicate-version-badge");
 const replace = require("replace-in-file");
-const outputDir = "docs/apis-tools/camunda-api-rest/specifications";
-const specFile = "api/camunda/camunda-openapi.yaml";
 const fs = require("fs");
 
-function preGenerateDocs() {
-  const originalSpec = fs.readFileSync(specFile, "utf8");
+function preGenerateDocs(config) {
+  const originalSpec = fs.readFileSync(config.specPath, "utf8");
 
   console.log("adjusting C8 spec file...");
 
@@ -14,18 +12,20 @@ function preGenerateDocs() {
     ...redefineCreateProcessInstanceRequest(originalSpec),
     ...redefineEvaluateDecisionRequest(originalSpec),
     ...addAlphaAdmonition(), // needs to go before addFrequentlyLinkedDocs
-    ...addFrequentlyLinkedDocs(),
+    ...addFrequentlyLinkedDocs(config.version),
   ];
 
   replace.sync({
-    files: specFile,
+    files: config.specPath,
     from: specUpdates.map((x) => x.from),
     to: specUpdates.map((x) => x.to),
   });
 }
 
-function postGenerateDocs() {
-  removeDuplicateVersionBadge(`${outputDir}/camunda-8-rest-api.info.mdx`);
+function postGenerateDocs(config) {
+  removeDuplicateVersionBadge(
+    `${config.outputDir}/camunda-8-rest-api.info.mdx`
+  );
 }
 
 function addDisclaimer(originalSpec) {
@@ -239,9 +239,20 @@ function addAlphaAdmonition() {
   ];
 }
 
-function addFrequentlyLinkedDocs() {
+function addFrequentlyLinkedDocs(version) {
   // This task is inherently repeatable, because the `match` is replaced by something that won't match again.
 
+  // The path to the alpha doc varies by version.
+  const otherAlphaPaths = {
+    8.6: "/reference/alpha-features.md",
+    8.5: "/reference/alpha-features.md",
+    8.4: "/reference/alpha-features.md",
+    8.3: "/reference/alpha-features.md",
+  };
+  const alphaPath =
+    otherAlphaPaths[version] ||
+    "/components/early-access/alpha/alpha-features.md";
+
   // Adds links to the Camunda Alpha REST API documentation, so that they don't have to live in the upstream spec.
   return [
     {
@@ -250,13 +261,12 @@ function addFrequentlyLinkedDocs() {
     },
     {
       from: /endpoint is an alpha feature/g,
-      to: "endpoint is an [alpha feature](/components/early-access/alpha/alpha-features.md)",
+      to: `endpoint is an [alpha feature](${alphaPath})`,
     },
   ];
 }
 
 module.exports = {
-  outputDir,
   preGenerateDocs,
   postGenerateDocs,
 };