Module Odoc_extension_apiSource

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.

Sourcemodule Comment = Odoc_model.Comment
Sourcemodule Location_ = Odoc_model.Location_

Extension Types

Sourcetype 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)

Sourcetype 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.

Sourcetype 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

Sourcetype 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

Sourcetype 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

Sourceexception Unsupported_tag of string

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

Extension Interface

Sourcemodule 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.

Sourcetype 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

Sourcemodule 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.

Sourcetype 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.

Sourcemodule Registry : sig ... end

Helper Functions

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

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

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

Create a simple paragraph block

Create an inline link

Sourceval simple_output : Block.t -> extension_output

Create an empty extension output with just content

Code Block Metadata Helpers

Sourceval 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".

Sourceval 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.

Sourceval 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

Sourceval 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