Docs: improve rendering of markdown READMEs

[MisterDA]

Hi all,
I've noticed a couple of issues with the way markdown READMEs are rendered. Most of the packages are hosted on GitHub, so I think it makes sense to mimic as much as possible how GitHub renders them, for consistency.

Let's have a look at how the alcotest-lwt package overview is rendered.

GFM is the name of the GitHub Flavored Markdown dialect.

1. Hard breaks vs soft breaks

   When rendering Markdown, inside a single block of text you can consider each line ending to be a hard-break and render the paragraph line by line, or render the whole paragraph as a single <p> block and concatenate the lines. GFM does the former for comments (issues, PRs, …) but the latter for text documents (READMEs). The result is that people don't care if their README is self-consistent with respect to column length of each paragraph line since GFM concatenates each line. The result is that the overview page has some paragraphs running at 70, 80, or 90 columns.

   My opinion is that the renderer should not consider line breaks inside a paragraph.
   GFM allows ending a line with two spaces to insert a hard break (but this is unpractical since some editors remove trailing whitespace) or (iirc) a backslash.

2. URL is counted as part of the line

   As line breaks are hard breaks, if one puts a link in the long form in a paragraph [example](https://example.com/a/very/long/url) they'll tend to insert a new line after. This leads to weird rendering.

   
   

3. Backticks rendered for inline-code

   For inline code, GitHub (and as far as I can tell, no one) renders the backtick. They are rendered in the docs website (but not as part of selectable text content, which is good). I personally highly dislike seeing them, I think they're part of markup and should not appear in rendered content.

   Anyway: if you want to have a backtick as part of inline code, you have to start the inline code with two backticks followed by a space, then your code, then two closing backticks. This can happen with OCaml code with polymorphic variants. Alcotest thus has this confusing text rendered:

   
   or
   
   Please consider not displaying these backticks.

4. Code is not syntactically highlighted

   Even though code blocks have the ocaml language tag, they're not syntactically highlighted. It would be nice to have colors!

Thanks!

[cuihtlauac]

Hi @MisterDA, thanks for reporting this. I believe you're right, items 1 to 3 are bugs indeed.

[cuihtlauac]

Item #3 is not an upstream issue. The CSS is faulty. This PR fixes the issue: #625

[sabine]

Hard breaks in README have been fixed by ocaml-doc/voodoo#119.

Opened a separate issue upstream for the missing syntax highlighting at ocaml-doc/voodoo#140. Closing this here.