We'll convert odoc HTML into GitHub Flavored Markdown (gfm), then we'll format the Markdown, after which we'll lift Markdown code blocks containing ::code-block:: LANGUAGE into Markdown fenced code blocks, and then use MyST to render the Markdown into HTML.

Basically: Odoc.html mli |> Pandoc.gfm |> Mdformat.format |> lift_code_block |> MyST_docutils.html5

The proposal is to render Odoc verbatim blocks of the form

::code-block:: LANGUAGE

source code
into syntax highlighted code blocks.

The design choices in the proposal are:

  1. Literate: Be understandable when the .mli file is read in a text editor
  2. Backwards-compatible: Not look like garbage if the feature is not available in an Odoc version

If the proposal is adopted, it may take quite a while before the proposal is implemented. In the meantime early adopters can use this experiment to adopt this feature into their own projects.

see the rendering of the .mli file

Please file an issue (or +1 an existing issue) if you like/dislike the proposal, or have implementation ideas. Visit