Skip to content

Commit 97c4bd0

Browse files
rosieyohannanrosieyohannan
authored
Merge pull request #9625 from circleci/DOCSS-1468-mermaid-diagrams
Add mermaid antora extension
2 parents ade14a3 + 163bd0f commit 97c4bd0

File tree

9 files changed

+267
-7
lines changed

9 files changed

+267
-7
lines changed

‎antora-playbook.yml‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,4 +66,15 @@ urls:
6666
html_extension_style: indexify
6767
antora:
6868
extensions:
69-
- ./extensions/unlisted-pages-extension.js
69+
- ./extensions/unlisted-pages-extension.js
70+
- require: '@sntke/antora-mermaid-extension'
71+
mermaid_initialize_options:
72+
start_on_load: true
73+
theme: base
74+
security_level: loose
75+
theme_variables:
76+
primary_color: '#E3F5E5'
77+
background: '#E3F5E5'
78+
line_color: '#B4B8C6'
79+
primary_border_color: '#008542'
80+
primary_text_color: '#00381A'

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

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,3 +97,16 @@ docs/
9797
└── settings.svg
9898
----
9999

100+
== Diagrams
101+
102+
You can add mermaid diagrams to a page, as follows:
103+
104+
.Example of a mermaid diagram
105+
[mermaid]
106+
....
107+
sequenceDiagram
108+
participant Alice
109+
participant Bob
110+
Alice->>Bob: Hello Bob, how are you?
111+
Bob-->>Alice: Great!
112+
....

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,17 @@ WARNING: *Want to see a warning?* This is a warning.
1616

1717
CAUTION: *Want to see a caution?* This is a caution.
1818

19+
== Diagram
20+
21+
[mermaid]
22+
....
23+
sequenceDiagram
24+
participant Alice
25+
participant Bob
26+
Alice->>Bob: Hello Bob, how are you?
27+
Bob-->>Alice: Great!
28+
....
29+
1930
Sometimes we have sections separated by horizontal lines, like this:
2031

2132
---

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

Lines changed: 86 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,92 @@ There are four types of jobs:
6969

7070
You can set the type of a job by adding the `type` key to the job configuration.
7171

72-
See the xref:reference:ROOT:configuration-reference.adoc#job-type[Confirguration reference] page for more information on how to use the different job types.
72+
See the xref:reference:ROOT:configuration-reference.adoc#job-type[Configuration reference] page for more information on how to use the different job types.
73+
74+
=== Job status transitions
75+
76+
The following diagram and table shows the possible job statuses and transitions.
77+
78+
.CircleCI cloud job status transitions
79+
[mermaid]
80+
----
81+
stateDiagram-v2
82+
direction TB
83+
[*] --> blocked
84+
85+
state "blocked or not running" as pending
86+
blocked --> pending : Job instructed to start but not yet started
87+
blocked --> unauthorized : Trying to use a context without permission
88+
89+
pending --> running
90+
91+
pending --> blocked : Rerun
92+
93+
running --> canceled
94+
pending --> canceled
95+
blocked --> canceled
96+
97+
pending --> failed : Abusive / Sanctioned
98+
running --> failed
99+
running --> success
100+
101+
failed --> [*]
102+
success --> [*]
103+
canceled --> [*]
104+
unauthorized --> [*]
105+
----
106+
107+
.CircleCI server job status transitions
108+
[mermaid]
109+
----
110+
stateDiagram-v2
111+
direction TB
112+
[*] --> blocked
113+
114+
state "blocked or not running" as pending
115+
blocked --> pending : Job instructed to start but not yet started
116+
blocked --> unauthorized : Trying to use a context without permission
117+
118+
pending --> running
119+
120+
pending --> skipped : Only build PRs setting enabled<br/>ci-skip<br/>No project found<br/>Abusive<br/>Sanctioned
121+
pending --> blocked : Rerun
122+
123+
running --> canceled
124+
pending --> canceled
125+
blocked --> canceled
126+
127+
running --> failed
128+
running --> success
129+
130+
skipped --> [*]
131+
success --> [*]
132+
failed --> [*]
133+
canceled --> [*]
134+
unauthorized --> [*]
135+
----
136+
137+
[cols="1,2", options="header"]
138+
|===
139+
| Status | Description
140+
141+
|Blocked/Not Running | All jobs start off in a blocked state. Jobs called `build` move on to a Not Running state before starting.
142+
143+
|Running | Job is running.
144+
145+
| On Hold | The job is running but requires manual approval.
146+
147+
| Not Run | The job is skipped.
148+
149+
| Success | The job succeeded.
150+
151+
| Failed | The job failed or terminated for unknown reasons.
152+
153+
| 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.
154+
155+
| Unauthorized | The job uses a restricted context and the actor that triggered the work does NOT have access to that context.
156+
157+
|===
73158

74159
[#steps-overview]
75160
== Steps overview

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

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,30 @@ Once you have set up a pipeline you need to set up a trigger to connect it to. S
114114
--
115115
====
116116

117+
== Pipeline states
118+
119+
The following diagram outlines the various states a pipeline can be in.
120+
121+
.Pipeline states
122+
[mermaid]
123+
----
124+
stateDiagram-v2
125+
direction TB
126+
state "Is this dynamic config?" as isdynamic
127+
[*] --> isdynamic
128+
state "setup-pending" as setuppending
129+
isdynamic --> setuppending : Yes
130+
isdynamic --> pending : No
131+
132+
setuppending --> setup
133+
setup --> pending
134+
pending --> created
135+
pending --> errored
136+
created --> [*]
137+
errored --> [*]
138+
139+
----
140+
117141
== Pipeline parameters
118142

119143
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‎

Lines changed: 79 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -846,7 +846,79 @@ image::guides:ROOT:orchestrate-and-trigger/rerun-from-failed-workflows-page.png[
846846
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.
847847

848848
[#states]
849-
=== Workflow states
849+
== Workflow states
850+
851+
The following state diagram shows the possible states and transitions of a workflow:
852+
853+
.CircleCI cloud workflow states
854+
[mermaid]
855+
----
856+
stateDiagram-v2
857+
[*] --> running
858+
859+
running --> success
860+
861+
running --> failing
862+
863+
running --> on_hold
864+
on_hold --> canceled
865+
on_hold --> running : approval job
866+
on_hold --> success
867+
868+
running --> canceled
869+
failing --> failed
870+
failing --> canceled
871+
872+
running --> failed
873+
running --> error
874+
running --> unauthorized
875+
876+
running --> queued
877+
queued --> running: queued as part of a serial group
878+
879+
success --> [*]
880+
canceled --> [*]
881+
failed --> [*]
882+
error --> [*]
883+
unauthorized --> [*]
884+
885+
----
886+
887+
.CircleCI server workflow states
888+
[mermaid]
889+
----
890+
stateDiagram-v2
891+
[*] --> running
892+
893+
running --> success
894+
895+
running --> failing
896+
897+
running --> on_hold
898+
on_hold --> canceled
899+
on_hold --> running : approval job
900+
on_hold --> success
901+
902+
running --> canceled
903+
failing --> failed
904+
failing --> canceled
905+
906+
running --> failed
907+
running --> error
908+
running --> not_run
909+
running --> unauthorized
910+
911+
running --> queued
912+
queued --> running: queued as part of a serial group
913+
914+
success --> [*]
915+
canceled --> [*]
916+
failed --> [*]
917+
error --> [*]
918+
unauthorized --> [*]
919+
not_run --> [*]
920+
921+
----
850922

851923
Workflows may have one of the following states:
852924

@@ -858,10 +930,6 @@ Workflows may have one of the following states:
858930
| Workflow is in progress
859931
| No
860932

861-
| NOT RUN
862-
| Workflow never started
863-
| Yes
864-
865933
| CANCELED
866934
| Workflow canceled before it finished
867935
| Yes
@@ -889,10 +957,16 @@ Workflows may have one of the following states:
889957
| UNAUTHORIZED
890958
| 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.
891959
| Yes
960+
961+
| QUEUED
962+
| The workflow is queued due to being part of a serial group. For more information, see the xref:controlling-serial-execution-across-your-organization.adoc[Controlling serial execution across your organization] page.
963+
| No
964+
892965
|===
893966

894967
NOTE: After 90 days non-terminal workflows are automatically cancelled by CircleCI.
895968

969+
896970
[#troubleshooting]
897971
== Troubleshooting
898972

‎package-lock.json‎

Lines changed: 7 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@
2222
"@antora/site-generator": "3.1.14",
2323
"@dotenvx/dotenvx": "^1.40.0",
2424
"@redocly/cli": "^2.0.0",
25+
"@sntke/antora-mermaid-extension": "^0.0.8",
2526
"browser-sync": "^3.0.4",
2627
"gulp": "^5.0.0",
2728
"snippet-enricher-cli": "0.0.8"

‎ui/src/css/doc.css‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1468,3 +1468,37 @@ td li code,
14681468
.doc td .listingblock code {
14691469
white-space: pre !important;
14701470
}
1471+
1472+
/* === MERMAID DIAGRAM STYLES === */
1473+
1474+
/* Basic container styling */
1475+
.doc .mermaid {
1476+
text-align: center;
1477+
margin: 1rem 0;
1478+
overflow-x: auto;
1479+
}
1480+
1481+
/* Responsive sizing */
1482+
.doc .mermaid svg {
1483+
max-width: 100%;
1484+
height: auto;
1485+
cursor: default; /* Prevent zoom cursor on hover */
1486+
}
1487+
1488+
/* Prevent zoom cursor on mermaid diagrams */
1489+
.doc .mermaid,
1490+
.doc .mermaid *,
1491+
.doc .imageblock .mermaid,
1492+
.doc .imageblock .mermaid *,
1493+
.doc .imageblock .content .mermaid,
1494+
.doc .imageblock .content .mermaid * {
1495+
cursor: default !important;
1496+
}
1497+
1498+
/* Specifically override the imageblock content zoom cursor when it contains mermaid */
1499+
.doc .imageblock .content .mermaid ~ *,
1500+
.doc .imageblock .content .mermaid + * {
1501+
cursor: default !important;
1502+
}
1503+
1504+

0 commit comments

Comments
 (0)