We'll convert odoc HTML into GitHub Flavored Markdown (gfm), and then we'll format the Markdown, and then use MyST to render the Markdown into HTML.

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

MyST has many features I (jonahbeckford@) would like to see in odoc. The pipeline in this experiment will let us:

• put some new processing instructions (future additions to odoc!) into an .mli or .mld (probably in the code blocks)
• translate those new processing instructions into MyST (probably using sed or regex)
• see the result without having to modify odoc (just make an experiment that extends this one)

The net effect is that the OCaml community gets to propose and see additions to odoc, and while the new feature may take years to implement, any early adopter can use the custom Dune rules from the experiment to adopt in their own projects. Early adoption will be complex but early adoption will also be future compatible.

Q: Why format the generated Markdown with mdformat?

ANS: The pandoc generated Markdown uses indented code rather than backticks for code blocks. Even with Markdown the backticks are better because you can specify the coding language for color formatting. For example:

```ocaml
let () = print_endline "hi"
```

MyST goes further and lets you place special instructions on those backticks. So by using mdformat we get three backticks for code blocks which we can easily extend with a bit of regex (ex. sed) to quickly implement whatever feature proposal we want for odoc.

The only real disadvantage to mdformat is that it advertises it is for CommonMark Markdown. At some point if these experiments are useful someone should write a Markdown formatter (in OCaml?) that works with GitHub Flavored Markdown.

Using pandoc to produce Github Flavored Markdown, and then MyST to render back to HTML results in little loss of information. pandoc and MyST are a good temporary solution until Issue #709 is complete.

The issues are identical to the GitHub Flavored Markdown experiment