We'll convert odoc HTML into GitHub Flavored Markdown (gfm), and then from gfm Markdown back to HTML.

Basically: Odoc.html mli |> Pandoc.gfm |> Pandoc.html

Typically we may just stop at Markdown since Markdown (together with YAML frontmatter) is the conventional content format for static site generators. GitHub Flavored Markdown is a common Markdown format, in use in GitHub (obviously) and in the Gatsby static site generator.

Converting again to HTML lets us visually inspect how much information has disappeared in the conversion to Markdown using pandoc.

test the Experiment Design rendering of comment markup in a .mli file. Compare to the original (100-plain) rendering

Using pandoc to produce Github Flavored Markdown results in little loss of information. pandoc is a good temporary solution until Issue #709 is complete.

  1. There are very minor spacing differences. Which is natural because you can't specify spacing in Markdown.
  2. OCaml and all other code blocks are not in color
  3. odoc 2.2.0: OCaml code blocks have an incorrect space between the backticks (```) and the language
  4. odoc 2.2.0: OCaml code blocks have the language language-ocaml rather than nothing (odoc 2.1.0) or the correct ocaml
  5. Raw HTML is lost completely
  6. At the bottom of the Results the module references are rendered incorrectly:
        module X`` `` :sig...end``
        module Y`` `` :sig...end``
    The original shows what it should have been:
        module X : sig ... end
        module Y : sig ... end