Design
We'll convert odoc HTML into CommonMark Markdown (commonmark), and then from commonmark Markdown back to HTML.
Basically: Odoc.html mli |> Pandoc.commonmark |> Pandoc.html
Typically we may just stop at Markdown since Markdown (together with YAML frontmatter) is the conventional content format for static site generators. CommonMark is a common Markdown format (no pun intended), and almost all Markdown tools can process CommonMark.
Converting again to HTML lets us visually inspect how much information has disappeared in the conversion to Markdown using pandoc.
Results
- markup.mli
- test the Experiment Design rendering of comment markup in a .mli file. Compare to the original (100-plain) rendering
Conclusion
Using pandoc to produce CommonMark Markdown results in some loss of information. Use GitHub Flavored Markdown as an intermediate file format instead because it loses less information!
CommonMark Markdown has all the same issues as GitHub Flavored Markdown, and it adds its own issues. See Experiment 200-gfm-lossiness for issues shared by both GitHub Flavored Markdown and CommonMark Markdown. CommonMark Markdown also:
- Loses the section anchors. Among other things, that makes the built-in table of contents useless