Markdown output

[davesnx]

Hi,

This PR might come out of the blue, but there's a good reason. Let me explain myself in the "Why" below.

Also, when I was half done, I discovered a stale PR (#791) targeting the same problem, and I thought it could be helpful to other people.

Why

We use odoc in Melange's documentation, to generate API references for Melange libraries, such as Belt, Js, and Stdlib. While the rest of the documentation is handled by vitepress a static site generator working with Markdown files, with a lot of interesting features.

This works reasonably well, but creates a big barrier between the documentation sites:

• Can't reference the melange.re docs articles from inside mld
• Search from melange.re docs don't find anything inside the generated HTML
• Users go from a unified experience to a different experience, melange.re is a SPA while generated HTML is an MPA
• Navigation on the header and sidebar isn't the same and can't be unified
• and a few more small details, such as favicon, tracking scripts, same syntax highlight and all features that a static site generator may give

For this reason, I wanted to generate markdown from odoc and (in the melange case) have another process that manipulates those markdown files to expand the documentation.

Another big use case for Markdown generation is Github, or any markdown renderer platform really.

How

I forked the HTML backend into a markdown2, removed what's unnecessary, and implemented Markdown construction with cmarkit.

I currently name it markdown2 since there is odoc_md and doc_of_md under the markdown folder. I suggest renaming markdown -> odoc-md (or just md) and markdown2 -> markdown in a new PR

Notes about implementation

• References aren't a thing in Markdown's headings. I removed them, but I could always render HTML and keep the references, but it would be better to have an option for this. WDYT about --allow-html where I enable this functionality of outputting HTML
• Similar cases for video/audio. Which isn't supported in pure markdown, but is supported in the CommonMark spec. We could fallback to HTML
• I left a few TODOS in the code that are mostly doubts/questions about odoc that could be good to have a 2nd pair of eyes
• All testing has been done in 2 cram tests: markdown-with-belt.t and markdown.t. I could probably split them or organise them differently

Example

melange-re/melange-re.github.io#224

Future work

• Add frontmatter into markdown
• The —allow-html option I mentioned above
• Talk about ODOC_SYNTAX="re_and_ml" ODOC_SYNTAX="re & ml" #1342