Module Odoc_extension_api

Odoc Extension API

This module provides the interface for odoc tag extensions. Extensions are dynamically loaded plugins that handle custom tags like @note, @rfc, @example, etc.

Re-exported Types

These are the odoc types that extensions need to work with.

module Comment = Odoc_model.Comment
module Location_ = Odoc_model.Location_
module Description = Odoc_document.Types.Description
module Url = Odoc_document.Url

Extension Types

type resource = Odoc_extension_registry.resource =
  1. | Js_url of string
    (*

    External JavaScript: <script src="...">

    *)
  2. | Css_url of string
    (*

    External CSS: <link rel="stylesheet" href="...">

    *)
  3. | Js_inline of string
    (*

    Inline JavaScript: <script>...</script>

    *)
  4. | Css_inline of string
    (*

    Inline CSS: <style>...</style>

    *)

Resources that can be injected into the page (HTML only)

type asset = Odoc_extension_registry.asset = {
  1. asset_filename : string;
    (*

    Filename for the asset, e.g., "diagram-1.png"

    *)
  2. asset_content : bytes;
    (*

    Binary content

    *)
}

Binary asset generated by an extension. Assets are written alongside the HTML output. To reference an asset in your content, use the placeholder __ODOC_ASSET__filename__ which will be replaced with the correct relative path during HTML generation.

Extension Documentation

Extensions can register documentation describing their options and usage. This information is displayed by odoc extensions --help.

type option_doc = Odoc_extension_registry.option_doc = {
  1. opt_name : string;
    (*

    Option name, e.g., "width"

    *)
  2. opt_description : string;
    (*

    What the option does

    *)
  3. opt_default : string option;
    (*

    Default value if any

    *)
}

Documentation for a single option

type extension_info = Odoc_extension_registry.extension_info = {
  1. info_kind : [ `Tag | `Code_block ];
    (*

    Type of extension

    *)
  2. info_prefix : string;
    (*

    The prefix this extension handles

    *)
  3. info_description : string;
    (*

    Short description

    *)
  4. info_options : option_doc list;
    (*

    Supported options

    *)
  5. info_example : string option;
    (*

    Example usage

    *)
}

Documentation/metadata for an extension

type extension_output = {
  1. content : Block.t;
    (*

    Universal content - used by all backends unless overridden

    *)
  2. overrides : (string * string) list;
    (*

    Backend-specific raw content overrides. E.g., ("html", "<div>...</div>"); ("markdown", "...")

    *)
  3. resources : resource list;
    (*

    Page-level resources (JS/CSS). Only used by HTML backend.

    *)
  4. assets : asset list;
    (*

    Binary assets to write alongside HTML output. Reference in content using __ODOC_ASSET__filename__ placeholder.

    *)
}

Output from the document phase

exception Unsupported_tag of string

Raised when an extension receives a tag variant it doesn't support

Extension Interface

module type Extension = sig ... end

The signature that all tag extensions must implement

Code Block Extensions

Extensions can also handle code blocks like {@dot[...]} or {@mermaid[...]}. These extensions receive the language tag, metadata (key=value pairs), and the code content.

type code_block_meta = Odoc_extension_registry.code_block_meta = {
  1. language : string;
    (*

    The language tag, e.g., "dot" or "mermaid"

    *)
  2. tags : Odoc_parser.Ast.code_block_tag list;
    (*

    Additional metadata tags like width=500 or format=svg. Each tag is either `Tag name for bare tags or `Binding (key, value) for key=value pairs.

    *)
}

Metadata for code blocks

module type Code_Block_Extension = sig ... end

The signature that code block extensions must implement

Support Files

Extensions can register support files (CSS, JS, images, etc.) that will be output by odoc support-files.

type support_file = Odoc_extension_registry.support_file = {
  1. filename : string;
    (*

    Relative path, e.g., "extensions/admonition.css"

    *)
  2. content : string;
    (*

    File content

    *)
}

Extension Registry

Extensions register themselves here when loaded. odoc queries the registry when processing custom tags.

module Registry : sig ... end

Helper Functions

Convert Comment AST to Block elements, preserving references and formatting. This is the proper way to convert tag content to renderable blocks.

val text_of_inline : Comment.inline_element Location_.with_location -> string

Extract plain text from nestable block elements (for simple parsing)

val text_of_inlines : Comment.inline_element Location_.with_location list -> string
val text_of_link_content : Comment.link_content -> string
val text_of_non_link : Comment.non_link_inline_element Comment.with_location -> string
val text_of_paragraph : Comment.paragraph -> string
val text_of_nestable_block_elements : Comment.nestable_block_element Location_.with_location list -> string
val paragraph : string -> Block.one list

Create a simple paragraph block

Create an inline link

val simple_output : Block.t -> extension_output

Create an empty extension output with just content

Code Block Metadata Helpers

val get_binding : 'a -> [< `Binding of 'a Odoc_parser.Loc.with_location * 'b Odoc_parser.Loc.with_location | `Tag of 'c ] list -> 'b option

Get the value of a binding from code block tags. E.g., for {@dot width=500[...]}, get_binding "width" meta.tags returns Some "500".

val has_tag : 'a -> [< `Binding of 'b | `Tag of 'a Odoc_parser.Loc.with_location ] list -> bool

Check if a bare tag is present in code block tags. E.g., for {@ocaml line-numbers[...]}, has_tag "line-numbers" meta.tags returns true.

val get_all_bindings : [< `Binding of 'a Odoc_parser.Loc.with_location * 'b Odoc_parser.Loc.with_location | `Tag of 'c ] list -> ('a * 'b) list

Get all bindings as a list of (key, value) pairs

val get_all_tags : [< `Binding of 'a | `Tag of 'b Odoc_parser.Loc.with_location ] list -> 'b list

Get all bare tags as a list of names