A mermaid extension for odoc
Add documentation for odoc extension plugins
Add index.mld files with usage examples for each extension:
- mermaid: Flowcharts, sequence diagrams, state diagrams, etc.
- msc: Message Sequence Charts for protocol documentation
- dot: Graphviz/DOT diagrams for graphs and trees
- admonition: Note, warning, tip, important callout blocks
- rfc: IETF RFC citations with automatic linking
Each extension now has its own documentation page demonstrating
the syntax and showing live rendered examples.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+143
+141
index.mld
+141
index.mld
···
1
+
{0 Mermaid Extension for odoc}
2
+
3
+
This extension adds support for {{:https://mermaid.js.org/}Mermaid} diagrams
4
+
in odoc documentation. Mermaid is a JavaScript-based diagramming tool that
5
+
renders Markdown-inspired text definitions into diagrams.
6
+
7
+
{1 Installation}
8
+
9
+
{[
10
+
opam install odoc-mermaid-extension
11
+
]}
12
+
13
+
Once installed, the extension is automatically loaded by odoc.
14
+
15
+
{1 Usage}
16
+
17
+
Use the [{@mermaid[...]}] tag to embed Mermaid diagrams:
18
+
19
+
{v
20
+
{@mermaid[
21
+
graph LR
22
+
A[Start] --> B{Decision}
23
+
B -->|Yes| C[OK]
24
+
B -->|No| D[Cancel]
25
+
]}
26
+
v}
27
+
28
+
{1 Examples}
29
+
30
+
{2 Flowchart}
31
+
32
+
{@mermaid[
33
+
graph TD
34
+
A[Christmas] -->|Get money| B(Go shopping)
35
+
B --> C{Let me think}
36
+
C -->|One| D[Laptop]
37
+
C -->|Two| E[iPhone]
38
+
C -->|Three| F[Car]
39
+
]}
40
+
41
+
{2 Sequence Diagram}
42
+
43
+
{@mermaid[
44
+
sequenceDiagram
45
+
participant Alice
46
+
participant Bob
47
+
Alice->>John: Hello John, how are you?
48
+
loop Healthcheck
49
+
John->>John: Fight against hypochondria
50
+
end
51
+
Note right of John: Rational thoughts!
52
+
John-->>Alice: Great!
53
+
John->>Bob: How about you?
54
+
Bob-->>John: Jolly good!
55
+
]}
56
+
57
+
{2 State Diagram}
58
+
59
+
{@mermaid[
60
+
stateDiagram-v2
61
+
[*] --> Still
62
+
Still --> [*]
63
+
Still --> Moving
64
+
Moving --> Still
65
+
Moving --> Crash
66
+
Crash --> [*]
67
+
]}
68
+
69
+
{2 Class Diagram}
70
+
71
+
{@mermaid[
72
+
classDiagram
73
+
Animal <|-- Duck
74
+
Animal <|-- Fish
75
+
Animal <|-- Zebra
76
+
Animal : +int age
77
+
Animal : +String gender
78
+
Animal: +isMammal()
79
+
Animal: +mate()
80
+
class Duck{
81
+
+String beakColor
82
+
+swim()
83
+
+quack()
84
+
}
85
+
]}
86
+
87
+
{2 Entity Relationship Diagram}
88
+
89
+
{@mermaid[
90
+
erDiagram
91
+
CUSTOMER ||--o{ ORDER : places
92
+
ORDER ||--|{ LINE-ITEM : contains
93
+
CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
94
+
]}
95
+
96
+
{2 Gantt Chart}
97
+
98
+
{@mermaid[
99
+
gantt
100
+
title A Gantt Diagram
101
+
dateFormat YYYY-MM-DD
102
+
section Section
103
+
A task :a1, 2024-01-01, 30d
104
+
Another task :after a1, 20d
105
+
section Another
106
+
Task in sec :2024-01-12, 12d
107
+
another task :24d
108
+
]}
109
+
110
+
{1 Options}
111
+
112
+
The extension supports the following options:
113
+
114
+
- [theme] - Mermaid theme: [default], [forest], [dark], [neutral]
115
+
- [width] - CSS width (e.g., [500px], [100%])
116
+
- [height] - CSS height
117
+
- [format] - Output format: omit for client-side JS, or [png]/[svg] for
118
+
server-side rendering (requires [mmdc] CLI tool)
119
+
120
+
{2 Theme Example}
121
+
122
+
{v
123
+
{@mermaid theme=forest[
124
+
graph LR
125
+
A --> B --> C
126
+
]}
127
+
v}
128
+
129
+
{@mermaid theme=forest[
130
+
graph LR
131
+
A --> B --> C
132
+
]}
133
+
134
+
{1 How It Works}
135
+
136
+
By default, diagrams are rendered client-side using the Mermaid JavaScript
137
+
library loaded from a CDN. The extension injects the necessary [<script>] tags
138
+
into the HTML output.
139
+
140
+
For server-side rendering (useful for PDF generation or environments without
141
+
JavaScript), install the [mmdc] CLI tool and use [format=png] or [format=svg].