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

  • admonition.note

    Note

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

Warning

  • admonition.warning

    Warning

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

Tip

  • admonition.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

  • admonition.important

    Important

    Important blocks highlight critical information that readers should not miss.

Admonition Kinds

The extension supports the following tag variants:

Tag

Purpose

@admonition or @admonition.note

General supplementary information

@admonition.tip

Helpful suggestions and best practices

@admonition.warning

Potential issues or things that could go wrong

@admonition.important

Critical information that should not be missed

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:

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