jon.recoil.org
Admonitions 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>
+98
index.mld
+98
index.mld
···
1
+
{0 Admonition Extension for odoc}
2
+
3
+
This extension adds support for admonition blocks (callouts) in odoc
4
+
documentation. Admonitions are used to highlight important information,
5
+
warnings, tips, and other notable content.
6
+
7
+
{1 Installation}
8
+
9
+
{[
10
+
opam install odoc-admonition-extension
11
+
]}
12
+
13
+
Once installed, the extension is automatically loaded by odoc.
14
+
15
+
{1 Usage}
16
+
17
+
Use the [@admonition] tag variants in documentation comments:
18
+
19
+
{v
20
+
(** Some documentation.
21
+
22
+
@admonition.note This is a note with important information.
23
+
*)
24
+
v}
25
+
26
+
{1 Examples}
27
+
28
+
{2 Note}
29
+
30
+
@admonition.note Notes are used for supplementary information that adds context or detail.
31
+
32
+
{2 Warning}
33
+
34
+
@admonition.warning Warnings alert readers to potential issues or things that could go wrong. Always validate user input before processing!
35
+
36
+
{2 Tip}
37
+
38
+
@admonition.tip Tips provide helpful suggestions or best practices. Use [Option.value ~default] instead of pattern matching when you just need a default value.
39
+
40
+
{2 Important}
41
+
42
+
@admonition.important Important blocks highlight critical information that readers should not miss.
43
+
44
+
{1 Admonition Kinds}
45
+
46
+
The extension supports the following tag variants:
47
+
48
+
{table
49
+
{tr
50
+
{th Tag}
51
+
{th Purpose}
52
+
}
53
+
{tr
54
+
{td [@admonition] or [@admonition.note]}
55
+
{td General supplementary information}
56
+
}
57
+
{tr
58
+
{td [@admonition.tip]}
59
+
{td Helpful suggestions and best practices}
60
+
}
61
+
{tr
62
+
{td [@admonition.warning]}
63
+
{td Potential issues or things that could go wrong}
64
+
}
65
+
{tr
66
+
{td [@admonition.important]}
67
+
{td Critical information that should not be missed}
68
+
}
69
+
}
70
+
71
+
{1 In API Documentation}
72
+
73
+
Admonitions are especially useful in module and function documentation:
74
+
75
+
{v
76
+
(** Connect to a database.
77
+
78
+
@admonition.warning This function will block until the connection
79
+
is established. Use {!connect_async} for non-blocking connections.
80
+
81
+
@admonition.tip For connection pooling, see {!Pool.create}.
82
+
*)
83
+
val connect : config -> t
84
+
v}
85
+
86
+
{1 Styling}
87
+
88
+
The extension generates HTML with appropriate CSS classes for styling.
89
+
Each admonition type has a distinct visual appearance with colors
90
+
that match its purpose:
91
+
92
+
- {b Note}: Blue, informational
93
+
- {b Tip}: Green, helpful
94
+
- {b Warning}: Orange, attention
95
+
- {b Important}: Red, critical
96
+
97
+
The CSS is automatically included when the extension is loaded and
98
+
supports both light and dark modes.