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

{v
::code-block:: LANGUAGE

source code
v}

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.

Please file an issue (or +1 an existing issue) if you like/dislike the proposal, or have implementation ideas. Visit https://github.com/diskuv/odoc-sandbox/issues.