jon.recoil.org

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: emitted as <script src="…">. Deduplicated by absolute URL on SPA navigation.

    *)
  2. | Css_url of string
    (*

    External CSS: emitted as <link rel="stylesheet" href="…">. Deduplicated by absolute URL on SPA navigation.

    *)
  3. | Js_inline of string
    (*

    Inline JavaScript: emitted as <script data-spa-inline="…">…</script>. Runs once on first encounter; skipped on subsequent SPA navigations that carry an identical script.

    *)
  4. | Css_inline of string
    (*

    Inline CSS: emitted as <style>…</style>. Re-injected on each SPA navigation (idempotent).

    *)

Resources that can be injected into the HTML <head>.

See Odoc_extension_registry for full documentation on execution timing, SPA deduplication semantics, and guidance for extension authors.

Summary:

  • Js_url / Css_url — deduplicated by resolved URL. Loaded at most once across SPA navigations.
  • Js_inline — stamped with data-spa-inline at generation time. Executed exactly once: on the first SPA navigation that introduces the script. Do not use DOMContentLoaded inside these; use a MutationObserver if you need to react to content changes on subsequent navigations.
  • Css_inline — injected on every navigation (CSS is additive and idempotent).
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 : Odoc_extension_api.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 : Odoc_extension_api.resource list;
    (*

    Page-level resources (JS/CSS). Only used by HTML backend. See resource for execution and deduplication semantics, especially in SPA (single-page app) shells.

    *)
  4. assets : Odoc_extension_api.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

Extensions that need to look up other pages or modules during linking can use the cross-reference environment.

Extension Interface

Sourcemodule type Extension = sig ... end

The signature that all tag extensions must implement

Extensions that also need link-time access to the cross-reference environment implement this extended signature.

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_content = Odoc_extension_registry.support_file_content =
  1. | Inline of string
  2. | Copy_from of string
Sourcetype support_file = Odoc_extension_registry.support_file = {
  1. filename : string;
    (*

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

    *)
  2. content : Odoc_extension_api.support_file_content;
}

Extension Registry

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

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

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

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