Tuleap uses michelf/php-markdown [0] to render Markdown which is nice but it is a specific Markdown implementation and Markdown does not have a specification (at least not one without too much ambiguities). This lead to different behaviors between different Markdown consumers: a same content can looks fine on one and be completely broken on another.

In order to solve that CommonMark [1] has been developed [2] and is now used (with some extensions) by large users like GitHub [3] and GitLab [4]. It would be nice to use a CommonMark implementation in Tuleap as well (yeah no more broken README.md when mirroring repositories o/).

There is a well maintained and high quality library in PHP [5] to render CommonMark content. A nice side effect is that this library can easily be extended so it would be possible for us to do smart things when rendering a Markdown file in a Git repositories like having the capability to have links to files in the repo or to display images located in the repository.



[0] https://github.com/michelf/php-markdown
[1] https://commonmark.org/
[2] https://xkcd.com/927/
[3] https://github.blog/2017-03-14-a-formal-spec-for-github-markdown/
[4] https://about.gitlab.com/blog/2019/06/13/how-we-migrated-our-markdown-processing-to-commonmark/
[5] https://github.com/thephpleague/commonmark