Documentation bug: markdown syntax errors

[erikmd]

How to reproduce?

• Browse:
  • http://ocaml-sf.org/learn-ocaml/tutorials/step-3.html
  • http://ocaml-sf.org/learn-ocaml/tutorials/step-8.html
• Search for the ``` pattern.

(the PRs #383 and #384 intended to fix theses were incomplete AFAICT)

[EmileRolley]

How this pages are generated @erikmd? (I found the mkdocs.yml file, but I don't know what to do with it...)

[erikmd]

Hi @EmileRolley, I've just seen your comment.

All pages available in https://ocaml-sf.org/learn-ocaml/ are directly translated by GitHub Pages' platform from this directory: https://github.com/ocaml-sf/learn-ocaml/tree/master/docs/ each time a commit is merged in master.
So fixing #399 would just amount to edit the step-3.md and step-8.md Markdown source files.

But regarding your last remark

(I found the mkdocs.yml file, but I don't know what to do with it...)

I dunno either: I only know that mkdocs.yml is not required to trigger some GitHub Pages' deployment.

However, I can see this file had been committed first in commit cbd2f06 which is entitled "adapt to readthedocs", so maybe @yurug would have more information regarding the role that could play mkdocs.yml:)

[EmileRolley]

Hi @erikmd, thanks for your response.

All pages available in https://ocaml-sf.org/learn-ocaml/ are directly translated by GitHub Pages' platform from this directory: https://github.com/ocaml-sf/learn-ocaml/tree/master/docs/ each time a commit is merged in master.
So fixing #399 would just amount to edit the step-3.md and step-8.md Markdown source files.

I'm concern to know how I can preview the html result done by editing the markdown files.. Maybe, there is a way to manually trigger the GitHub pages?

[erikmd]

I'm concern to know how I can preview the html result done by editing the markdown files.. Maybe, there is a way to manually trigger the GitHub pages?

I usually do one of these:

1. either I directly perform the Markdown editing in GItHub, then I click on Preview changes before committing in a branch:
   https://docs.github.com/en/github/managing-files-in-a-repository/managing-files-on-github/editing-files-in-your-repository
2. or I use some editor with Markdown syntax highlighting, then generate the corresponding HTML by running:
   pandoc -f gfm -t html file.md -o file.html

but sometimes 2. is not precise enough to emulate GitHub's algo for rendering Markdown, so I guess 1. is more reliable.

[EmileRolley]

I see, thanks. I will see what I can do then :)

[EmileRolley]

After a quick try, I did not succeed to reproduce the bugs with the GitHub editor... However, it seems that the problem is caused by using code blocks inside lists. So, maybe replacing all * <list-elem> with **<list-elem>** could resolve the issue.