Admonition Extension for odoc

This extension adds support for admonition blocks (callouts) in odoc documentation. Admonitions are used to highlight important information, warnings, tips, and other notable content.

Installation

opam install odoc-admonition-extension

Once installed, the extension is automatically loaded by odoc.

Usage

Use the @admonition tag variants in documentation comments:

(** Some documentation.

    @admonition.note This is a note with important information.
*)

Examples

Note

• Note

  Notes are used for supplementary information that adds context or detail.

Warning

• Warning

  Warnings alert readers to potential issues or things that could go wrong. Always validate user input before processing!

Tip

• Tip

  Tips provide helpful suggestions or best practices. Use Option.value ~default instead of pattern matching when you just need a default value.

Important

• Important

  Important blocks highlight critical information that readers should not miss.

Admonition Kinds

The extension supports the following tag variants:

In API Documentation

Admonitions are especially useful in module and function documentation:

(** Connect to a database.

    @admonition.warning This function will block until the connection
    is established. Use {!connect_async} for non-blocking connections.

    @admonition.tip For connection pooling, see {!Pool.create}.
*)
val connect : config -> t

Styling

The extension generates HTML with appropriate CSS classes for styling. Each admonition type has a distinct visual appearance with colors that match its purpose:

• Note: Blue, informational
• Tip: Green, helpful
• Warning: Orange, attention
• Important: Red, critical

The CSS is automatically included when the extension is loaded and supports both light and dark modes.