Add mermaid antora extension

antora-playbook.yml

@@ -66,4 +66,19 @@ urls:
   html_extension_style: indexify
 antora:
   extensions:
-  - ./extensions/unlisted-pages-extension.js
+  - ./extensions/unlisted-pages-extension.js
+  - require: '@sntke/antora-mermaid-extension'
+    mermaid_initialize_options:
+      start_on_load: true
+      theme: base
+      security_level: loose
+      theme_variables:
+        primary_color: '#000000'
+        primary_text_color: '#161616'
+        primary_border_color: '#90f2a9'
+        line_color: '#90a8f2'
+        secondary_color: '#f290d9'
+        tertiary_color: '#e8edfc'
+        background: '#FFFFFF'
+        main_bkg: '#f290d9'
+        text_color: '#161616'

docs/contributors/modules/docs-style/pages/using-images.adoc

@@ -97,3 +97,16 @@ docs/
                     └── settings.svg
 ----
 
+== Diagrams
+
+You can add mermaid diagrams to a page, as follows:
+
+.Example of a mermaid diagram
+[mermaid]
+....
+sequenceDiagram
+    participant Alice
+    participant Bob
+    Alice->>Bob: Hello Bob, how are you?
+    Bob-->>Alice: Great!
+....

docs/contributors/modules/templates/pages/test-page-one.adoc

@@ -16,6 +16,17 @@ WARNING: *Want to see a warning?* This is a warning.
 
 CAUTION: *Want to see a caution?* This is a caution.
 
+== Diagram
+
+[mermaid]
+....
+sequenceDiagram
+    participant Alice
+    participant Bob
+    Alice->>Bob: Hello Bob, how are you?
+    Bob-->>Alice: Great!
+....
+
 Sometimes we have sections separated by horizontal lines, like this:
 
 ---

docs/guides/modules/orchestrate/pages/jobs-steps.adoc

@@ -69,7 +69,66 @@ There are four types of jobs:
 
 You can set the type of a job by adding the `type` key to the job configuration.
 
-See the xref:reference:ROOT:configuration-reference.adoc#job-type[Confirguration reference] page for more information on how to use the different job types.
+See the xref:reference:ROOT:configuration-reference.adoc#job-type[Configuration reference] page for more information on how to use the different job types.
+
+=== Job status transitions
+
+The following diagram and table shows the possible job statuses and transitions.
+
+.Job status transitions
+[mermaid]
+----
+stateDiagram-v2
+    direction TB
+    [*] --> blocked
+
+    state "blocked or not running" as pending
+    blocked --> pending : Job instructed to start but not yet started
+    blocked --> unauthorized : Trying to use a context without permission
+    blocked --> canceled
+
+    pending --> running
+
+    pending --> skipped : Only build PRs setting enabled<br/>ci-skip<br/>No project found<br/>Abusive<br/>Sanctioned
+    pending --> blocked : Rerun
+
+    running --> canceled
+    pending --> canceled
+
+
+
+    running --> failed
+    running --> success
+
+    skipped --> [*]
+    success --> [*]
+    failed --> [*]
+    canceled --> [*]
+    unauthorized --> [*]
+
+----
+
+[cols="1,2", options="header"]
+|===
+| Status | Description
+
+|Blocked/Not Running | All jobs start off in a blocked state. Jobs called `build` move on to a Not Running state before starting.
+
+|Running | Job is running.
+
+| On Hold | The job is running but requires manual approval.
+
+| Not Run | The job is skipped.
+
+| Success | The job succeeded.
+
+| Failed | The job failed or terminated for unknown reasons.
+
+| Canceled | The job was canceled. An actor might cancel a job, or cancel a workflow. A job may be cancelled due to auto-cancellation. Support engineers can force cancellation of a job.
+
+| Unauthorized | The job uses a restricted context and the actor that triggered the work does NOT have access to that context.
+
+|===
 
 [#steps-overview]
 == Steps overview

docs/guides/modules/orchestrate/pages/pipelines.adoc

@@ -114,6 +114,30 @@ Once you have set up a pipeline you need to set up a trigger to connect it to. S
 --
 ====
 
+== Pipeline states
+
+The following diagram outlines the various states a pipeline can be in.
+
+.Pipeline states
+[mermaid]
+----
+stateDiagram-v2
+    direction TB
+    state "is this dynamic config?" as isdynamic
+    [*] --> isdynamic
+    state "setup-pending" as setuppending
+    isdynamic --> setuppending : Dynamic config enabled<br/>and setup true in config
+    isdynamic --> pending : Dynamic config not enabled,<br/>or setup true not in config
+
+    setuppending --> setup
+    setup --> pending
+    pending --> created
+    pending --> errored
+    created --> [*]
+    errored --> [*]
+
+----
+
 == Pipeline parameters
 
 Pipeline parameters are declared using the `parameters` key at the top level of a `.circleci/config.yml` file. Pipeline parameters can be referenced by value and used as a configuration variable under the scope `pipeline.parameters`.

docs/guides/modules/orchestrate/pages/workflows.adoc

@@ -821,7 +821,7 @@ image::guides:ROOT:orchestrate-and-trigger/rerun-from-failed-workflows-page.png[
 NOTE: If you rerun a workflow containing a job that was previously re-run with SSH, the new workflow runs with SSH enabled for that job, even after SSH capability is disabled at the project level.
 
 [#states]
-=== Workflow states
+== Workflow states
 
 Workflows may have one of the following states:
 
@@ -864,10 +864,54 @@ Workflows may have one of the following states:
 | UNAUTHORIZED
 | One or more of the jobs terminated with a `unauthorized` job status. The user who triggered the pipeline or approved an approval job does not have access to a required restricted context.
 | Yes
+
+| QUEUED
+| The workflow is queued due to being part of a serial group. For more informaiton, see the xref:controlling-serial-execution-across-your-organization.adoc[Controlling serial execution across your organization] page.
+| No
+
 |===
 
 NOTE: After 90 days non-terminal workflows are automatically cancelled by CircleCI.
 
+The following state diagram shows the possible states and transitions of a workflow:
+
+.Workflow states
+[mermaid]
+----
+stateDiagram-v2
+    [*] --> running
+
+    running --> success
+
+    running --> failing
+
+    running --> on_hold
+    on_hold --> canceled
+    on_hold --> running : approval job
+    on_hold --> success
+
+    running --> canceled
+    failing --> failed
+    failing --> canceled
+
+    running --> failed
+    running --> error
+    running --> not_run
+    running --> unauthorized
+
+    running --> queued
+    queued --> running: queued as part of a serial group
+
+    success --> [*]
+    canceled --> [*]
+    failed --> [*]
+    error --> [*]
+    unauthorized --> [*]
+    not_run --> [*]
+
+----
+
+
 [#troubleshooting]
 == Troubleshooting
 

package.json

@@ -22,6 +22,7 @@
     "@antora/site-generator": "3.1.12",
     "@dotenvx/dotenvx": "^1.40.0",
     "@redocly/cli": "^2.0.0",
+    "@sntke/antora-mermaid-extension": "^0.0.8",
     "browser-sync": "^3.0.4",
     "gulp": "^5.0.0",
     "snippet-enricher-cli": "0.0.8"

ui/src/css/doc.css

@@ -1452,3 +1452,37 @@ td li code,
 .doc td .listingblock code {
   white-space: pre !important;
 }
+
+/* === MERMAID DIAGRAM STYLES === */
+
+/* Basic container styling */
+.doc .mermaid {
+  text-align: center;
+  margin: 1rem 0;
+  overflow-x: auto;
+}
+
+/* Responsive sizing */
+.doc .mermaid svg {
+  max-width: 100%;
+  height: auto;
+  cursor: default; /* Prevent zoom cursor on hover */
+}
+
+/* Prevent zoom cursor on mermaid diagrams */
+.doc .mermaid,
+.doc .mermaid *,
+.doc .imageblock .mermaid,
+.doc .imageblock .mermaid *,
+.doc .imageblock .content .mermaid,
+.doc .imageblock .content .mermaid * {
+  cursor: default !important;
+}
+
+/* Specifically override the imageblock content zoom cursor when it contains mermaid */
+.doc .imageblock .content .mermaid ~ *,
+.doc .imageblock .content .mermaid + * {
+  cursor: default !important;
+}
+
+